How can I write code without "needing" comments for readability?

Question

Possible Duplicate:
Is it possible to write good and understandable code without any comments?

When coding often I hear that if comments are needed then it means that the code is too hard to understand. I agree that code should be readable but often the language itself makes the code hard to follow, because of "plumbing" and strange syntax. The languages I use most often are:

Java Mootools Ruby Erlang

Any tips would be appreciated? Thanks

Answer 1

Recommended reading: Clean Code by Robert C. Martin.

In brief, you should

• use meaningful variable/method/class names,
• keep your functions/methods short,
• have each class and method do only one thing,
• have the code in each method be on the same level of abstraction.

Don't fear of extracting even moderately complex expressions from if statements; which one is clearer to read, this

if (i >= 0 && (v.size() < u || d == e)) ...

or

if (foundNewLocalMaximum()) ...

(Don't try to find any meaning in the first code snippet, I just made it up :-)

Comments in clean code are almost never needed. The only exceptions I can think of is if you are using some obscure language feature (e.g. C++ template metaprogramming) or algorithm, and you give a reference to the source of the method/algorithm and its implementation details in a comment.

The main reason why any other kind of comments is not very useful in the long run is that code changes, and comments tend to not be updated alongside the changes in the corresponding code. So after a while the comment is not simply useless, but it is misleading: it tells you something (implementation notes, reasoning about design choices, bug fixes etc.) which refers to a version of the code which is long gone, and you have no idea whether it is relevant anymore for the current version of the code.

Another reason why I think that "why I chose this solution" is most often not worth documenting in the code, is that the brief version of such a comment would almost always be like either "because I think this is the best way", or a reference to e.g. "The C++ Programming Language, ch. 5.2.1", and the long version would be a three-page essay. I think that an experienced programmer most often sees and understands why the code is written like this without much explanation, and a beginner may not understand even the explanation itself - it's not worth trying to cover everyone.

Last but not least, IMO unit tests are almost always a better way of documentation than code comments: your unit tests do document your understanding, assumptions and reasoning about the code quite efficiently, moreover you are automatically reminded to keep them in sync with the code whenever you break them (well, provided you actually run them with your build...).

Answer 2

I don't think you can normally write code without comments.

Briefly, the code documents how. The comments document why.

I would expect the comments to indicate the conditions why the code has been written like that, limitations imposed by requirements or externalities, the impact that would result from changing the code, and other gotchas. The comments contain information that isn't contained within the code itself.

Answer 3

Comments along the code are supposed to tell you why you initially did something a certain way. It shouldn't mean the code is too hard to understand.

Answer 4

The most important things to follow are:

• give your variables, methods, classes... meaningful names
• write classes/ modules with a clean responsibility
• don't mix up different levels of code (don't do bit shifting and high level logic inside of one method)

Answer 5

You need to follow certain rules.

• Give the entities (variable, classes, etc) readable and meaningful names.
• Use design patterns extensively and name them accordingly, e.g. if it is a Factory name it FooFactory.
• Have the code formatted properly, etc.

Answer 6

I think it is useful to write comments for USERS of your code - what the classes/methods/functions do, when an how to call it etc. In other words document the API.

If you need to comment how a method works for the benefit of maintainers then I think the code is probably too complex. In that case refactor it into simpler functions, as others have said.

Answer 7

I personally feel that having no comments at all is about as bad as having excessive commenting. You just need to find the right balance. About using long descriptive names for things this about sums it up for me: read this Also read Kernighan & Pike on long names.