What does a good programmer's code look like? [closed]

Question

The list below is not comprehensive, but these are the things that I thought of in considering your question.

• Good code is well-organized. Data and operations in classes fit together. There aren't extraneous dependencies between classes. It does not look like "spaghetti."

• Good code comments explain why things are done not what is done. The code itself explains what is done. The need for comments should be minimal.

• Good code uses meaningful naming conventions for all but the most transient of objects. the name of something is informative about when and how to use the object.

• Good code is well-tested. Tests serve as an executable specification of the code and examples of its use.

• Good code is not "clever". It does things in straightforward, obvious ways.

• Good code is developed in small, easy to read units of computation. These units are reused throughout the code.

I haven't read it yet, but the book I'm planning to read on this topic is Clean Code by Robert C. Martin.

The first thing you'd notice is that their code follows a consistent coding-style. They always write their structure blocks the same, indent religiously and comment where appropriate.

The second things you'd notice is that their code is segmented into small methods / functions spanning no more than a couple dozen lines at the most. They also use self describing method names and generally their code is very readable.

The third thing you'd notice, after you messed around with the code a little is that the logic is easy to follow, easy to modify - and therefore easily maintainable.

After that, you'll need some knowledge and experience in software design techniques to understand the specific choices they took constructing their code architecture.

Regarding books, I haven't seen many books where the code could be considered "world-class". In books they try mostly to present simple examples, which might be relevant to solving very simple problems but aren't reflective of more complex situations.

Quoting Fowler, summizing readability:

Any fool can write code that a computer can understand.
Good programmers write code that humans can understand.

'nough said.

Personally, I'll have to quote "The Zen of Python" by Tim Peters. It tells Python programmers what their code should look like, but I find that it applies to basically all code.

Beautiful is better than ugly.
Explicit is better than implicit.
Simple is better than complex.
Complex is better than complicated.
Flat is better than nested.
Sparse is better than dense.
Readability counts.
Special cases aren't special enough to break the rules.
Although practicality beats purity.
Errors should never pass silently.
Unless explicitly silenced.
In the face of ambiguity, refuse the temptation to guess.
There should be one-- and preferably only one --obvious way to do it.
Although that way may not be obvious at first unless you're Dutch.
Now is better than never.
Although never is often better than right now.
If the implementation is hard to explain, it's a bad idea.
If the implementation is easy to explain, it may be a good idea.
Namespaces are one honking great idea -- let's do more of those!

Code is poetry.

Start from this point of logic and you can derive many of the desirable qualities of code. Most importantly, observe that code is read far more than it is written, hence write code for the reader. Rewrite, rename, edit, and refactor for the reader.

A follow on corollary:

The reader will be you at time n from the code creation date. The payoff of writing code for the reader is a monotonically increasing function of n. A reader looking at your code for the first time is indicated by n == infinity.

In other words, the larger the gap of time from when you wrote the code to when you revisit the code, the more you will appreciate your efforts to write for the reader. Also, anyone you hand your code off to will gain great benefit from code written with the reader as the foremost consideration.

A second corollary:

Code written without consideration for the reader can be unnecessarily difficult to understand or use. When the consideration for the reader drops below a certain threshold, the reader derives less value from the code than the value gained by rewriting the code. When this occurs the previous code is thrown away and, tragically, much work is repeated during the rewrite.

A third corollary:

Corollary two has been known to repeat itself multiple times in a vicious cycle of poorly documented code followed by forced rewrites.