Is it possible to write good and understandable co

Question

Can any one suggest what is the best way to write good code that is understandable without a single line of comments?

Answer 1

Read Code Complete, 2nd Edition cover to cover. Perhaps twice.

To give some specifics:

• Making code readable
• Eliminating code repetition
• Doing design/architecture before you write code

Answer 2

I think comments should express the why, perhaps the what, but as much as possible the code should define the how (the behavior).

Someone should be able to read the code and understand what it does (the how) from the code. What may not be obvious is why you would want such behavior and what this behavior contributes to the overall requirements.

The need to comment should give you pause, though. Maybe how you are doing it is too complicated and the need to write a comment shows that.

There is a third alternative to documenting code - logging. A method that is well peppered with logging statements can do a lot to explain the why, can touch on the what and may give you a more useful artifact than well named methods and variables regarding the behavior.

Answer 3

I'm not sure writing code that is so expressive that you don't need comments is necessarily a great goal. Seems to me like another form of overoptimization. If I were on your team, I'd be pleased to see clear, concise code with just enough comments.

Answer 4

Yes, you can write code that doesn't need comments to describe what it does, but that may not be enough.

Just because a function is very clear in explaining what it does, does not, by itself, tell you why it is doing what it does.

As in everything, moderation is a good idea. Write code that is explanatory, and write comments that explain why it is there or what assumptions are being made.

Answer 5

Descriptive names is your obvious first bet.

Secondly make sure each method does one thing and only one thing. If you have a public method that needs to do many things, split it up into several private methods and call those from the public method, in a way that makes the logic obvious.

Some time ago I had to create a method that calculated the correlation of two time series.

To calculate the correlation you also need the mean and standard deviation. So I had two private methods (well actually in this case they were public as they could be used for other purposes (but assuming they couldn't then they would be private)) for calculating A) the mean, B) the standard deviation.

This sort of splitting up of function into the smallest part that makes sense is probably the most important thing to make a code readable.

How do you decide where to break up methods. My way is, if the name is obvious e.g. getAddressFromPage it is the right size. If you have several contenders you are probably trying to do too much, if you can't think of a name that makes sense you method may not "do" enough - although the latter is much less likely.

Answer 6

I don't really think comments are a good idea in most cases. Comments don't get checked by the compiler so they so often are misleading or wrong as the code changes over time. Instead, I prefer self documenting, concise methods that don't need comments. It can be done, and I have been doing it this way for years.

Writing code without comments takes practice and discipline, but I find that the discipline pays off as the code evolves.