WritingEffectiveComments

#Writing effective comments

Prefer write comments to clarify your intentions, as the author. Where possible, let code be it's own documentation.

##Good comments

Good comments describe the decisions the programmer made, and the thought process s/he considered, while writing the code.

Especially good comments identify areas of confusion in the code and detail the intentions behind it ("Ah! You must be thinking, why didn't I just write xxx? Well, it's because...").

Comments that just rephrase the code are less helpful (and sometimes can add confusion). If the intentions of the code are not clear, it may be better to change implementation. Perhaps by breaking it up into more functions/methods?

It's true that that is not always possible, however.

Here, I'm not talking about comments that will be read by a documentation generation tool (like Doxygen). I'm talking about comments inside of functions.

Consider:

... this past unfinished!! ...

Well commented code should be a sign that the programmer gave a lot of thought as to how to write that code.

###Restructuring code for clarity