Recently, I read an Article where the author, Jerry Low, suggested that developers write their CSS properties in alphabetical order. I think this is a great idea, and it got me thinking what some other tips for writing clean and readable code? Feel free to share your suggestions.
For further actions, you may consider blocking this person and/or reporting abuse
Top comments (31)
I read that article out of curiosity and I have to say, I am more than just a bit irritated by it.
The article is a perfect example of someone selling a personal preference as if its a fact which everyone should obey.
The autor even admits that after doing some research he found out that just about 10% of other developers follow his example and the majority does logical grouping.
I have to say, I think alphabetical oordering is just as bad as random ordering. The two examples looked exactly the same for me. I am very much in favor of the logical grouping (with blank lines in between!) and think its much easier to scan over.
But still: is is preference and not "clean code".
If you think about improving your general coding abilities, I can warmly recommend two books:
A philosophy of software design
by John Ousterhout
Refactoring (second edition)
by Martin Fowler
I learned a lot out of these two books.
Thanks for sharing your perspective, it's cool to read an opposing viewpoint on this article. Everyone has different personal preferences as it pertains to the way they code. After reading your comment, I can understand why the article can rub some people the wrong way.
switch/case
is evil.I don't get the problem with switch case. Can you provide an example?
switch/case
is often abused to express data that should be a map as control flow instead. Then people wonder why their code is so hard to extend.Ok... but if I don't use Python, I can't put everything in a map.
Yes, you can? What programming language doesn't support maps these days?
Efficiency in what sense though? Clean code is usually easier to maintain, making work more efficient.
I've been in code reviews where code was rejected in favour of "cleaner" code, despite being many orders of magnitude faster. Later, clients complain about performance. Madness
But those cases are often just a false dichotomy. Usually, it works something like this:
The right solution is obviously to spend the extra time to figure out how to make the good solution actually look clean, but if you ignore that option entirely, you can claim to decide between performance and readability.
When people find problems that really can't be expressed cleanly without a massive performance loss, they're either writing a C compiler, or they haven't spent enough time looking for a better solution.
I follow the 3 "make" rule when programming:
The clean code will appear between the steps 2 & 3.
I recently wrote all of these rules down for myself. The document is more than 600 lines long, so here are my 3 most important
tldr
s. All of them are inspired by Uncle Bob's best seller.1. Write code so it resembles its own specification
I find this the most relevant point, but also the hardest. I got the idea by combining the rule 'Use intention-revealing names' from Clean Code and 'Start Statements with Verbs' and 'Be brief' from Microsoft's writing guidelines.
A bit easier to imagine is: Write code like you write a newspaper article. A common rule here is The Pyramid Principle of writing. So all those essays in highschool were actually good for something
2. Prefer readability over performance
You might have noticed there's a pattern already. Code must be read by people, not machines. In most of the cases, the fancy JS 1-liners come with a trade-off in readability. MS writing guidelines support this - 'Write like you speak' tells you to write like a person, not a machine.
3. Do proper error handling and always do it the same way
The idea for this comes from the chapter 'Use special error objects'.
In Typescript, the type looks like this:
It's used in this function (async example):
For sync, just leave out the
async/await
and thePromise
generics.I don't like point #2, there's source code and compiled code. Those fancy "JS one-liners" aren't even meant to be read, they're optimized and compiled source code. Best practices and idiomatic code can lead to good readability and performance.
Maybe I've phrased myself poorly here. What I meant to say is: I'd prefer function code like this:
over this one:
in more complex settings.
I've seen a 50-liner in a productive codebase during last hacktoberfest and I found it rather hard to decipher due to these constructions.
If you chain the above example to a single function called
duplicateNumbersAndSumAllAboveFive
, fine by me. If you do three other things along the way, you should think about refactoring. Or at least make debugging less messy.To me the second example is much easier to read, as I don't have to make the connection between the four variables on my own. I can read it like "ok, I want numbers doubled above five and summed up. I take the numbers, map to their double, filter all above 5 and apply a standard sum reduce.
Then let me give you another example.
The following code snippet is meant to provide state for a react component (this - context = applicationwide state). I have slightly changed the original variable names, otherwise it's the same logic.
I then gave myself 10 minutes to try and refactor the function. When I put both into my text editor and try to debug, the second function is surely easier on the eye than the first. I might be wrong though, that's just my opinion.
Original
My 'debugable' approach
To me, it's usually a triangle: Efficiency, readability, abstraction.
However, it's rarely the same distribution, as it can vary from one project to another, depending on the context. I can't give a general rule but this how I see the project in terms of clean code.
You can't neglect performances but you have to avoid micro-optimization, especially when the code becomes too "ninja", a.k.a. less readable and maintainable. If you're the only one who can modify the script, it can become a problem quickly.
Too much abstraction is not really good in my experience. It can jam code reviews significantly. Besides, you can get a lot of unwanted side effects, so more stress for maintenance, etc.
About the article, I feel that is more personal taste than some pragmatic thing. There is a big difference between opinion (which everyone has) and well-known metrics such as SLOC, Cyclomatic Complexity and so on.
As tips, I suggest reading those books:
As a general rules of thumb that I like to follow:
use
in React Hooks). Each object should tell a story, each object should deserve its place in the source code by the story that it tells, not by its name.To me, a clean code rule has to be something that is worth the effort in the end.
I'm not that fast at alphabetical sorting, so I would take a lot of extra time and it would exceed the benefits it could provide.
My favourite type of sorting is the one my IDE does on autoformat.
Imagine while coding the colleague who has to maintain the code after you is a violent psychopath who knows where you live. 😅
The more articles I read on "clean code", the more it reminds me of a religion or a cult :)
I have a simple, modest suggestion: Almost every programming ecosystem has tools (pretty-printers, code formatters, or code beautifiers, depending on how old your language is...) to enforce a style. Just do what they say for new code, instead of arguing about style. Don't like that style? Use the same tool, configured to whatever style that you would prefer to look at.
Seriously, after sixty years of code, we need to stop wasting time arguing over style preferences. Let
cb
,prettier
,gofmt
,rustfmt
, or whatever do that thinking. The format doesn't matter, as long as everybody commits to the same standard. An exception, as hinted above: Leave the pre-beautifier code alone, until you need to change it. Nobody needs a ticket to automatically fix the indentation on a million lines of code written before they were born...And then the time saved on arguing about format can go to fixing all the warnings that the linter keeps complaining about that you either don't know about because you're not running your linter, or have been ignoring because "it's only a warning."