Clarity is the #1 priority when writing code. Clarity trumps everything else; it’s even more important than the code being correct! One of the biggest wins a serious programmer can offer is writing clear, readable code.

Source code is for the human reader; we don’t write it like that for the computer, we write it for us. If it were up to the computer, humans would use the same ones and zeros it does. It would be much more efficient that way.

But we (inefficient) humans need ways to write and talk about computer programs. We’ve invented many languages — computer languages — to do that in a variety of ways. And when we write in these languages, it is crucial to be clear.

Clarity is more important than correctness, because clear code can be fixed if it’s incorrect.

Unclear code is harder to work with. It’s harder to find, let alone fix, bugs. Clear code also helps debug as you write; you are more likely to catch your own errors when you write clear code.

(Not to say that correctness isn’t important; obviously it’s crucial. But clarity still trumps it exactly because of the realities expressed above plus the fact that perfect correctness is nearly impossible, so you’d better have clear code!)

Clarity is more important than comments, because clear code is readable! Part of clarity is using good object names and good coding style, and that helps the code be self-documenting.

On the other hand, writing clear code includes writing good comments, so don’t skip commenting just because you think you write very clear code. In fact, writing good comments is such a close second, that it’s hard not to argue it’s tied for first as being a #1 priority when writing code.

[But if I had to pick which mess I’d rather not clean up, clear code with no comments wins easily. It’s easier to add comments to clear, but undocumented, code than to clear up the commented code that’s a complete mess.]

Clarity is important, because it enables change. Clear code has a longer life. Unclear code can be difficult (or impossible) to maintain. I have sometimes found it easier to throw code away and start fresh, than to try to work with “a big ball of mud.” Clear code is maintainable and reusable.