Commentstipation

When it comes to commenting the code, the cat gets the typing fingers of even creative and knowledgeable programmers. Often we are focused on just getting the code working (We'll comment later! The code has to work first!) and then we forget (what was that again? it's obvious, also time to go home...)!

Code should be self-explanatory and hence self-commenting, as far as possible. But this definitely does not mean that there should be no comments.

Good comments are hard to come by because of -
a) I-Am-A-Programmer-Not-A-Writer attitude
Well, you are a writer too.

b) "I don't know English that well" excuse
Grammatical errors are fine, spelling mistakes are also OK. Write in your native tongue and translate it, if need be. And, if what the code does is that tough to explain, then it's also the more reason to document it, it probably needs to be documented!

Remember the programming adage: Documentation is like sex, something is better than nothing! ;-) But, it must be said, inaccurate documentation is worse than no documentation. An addition to the adage is perhaps needed...having it the wrong way is probably worse than not having it at all! ;-)

TIPS
--------
* A comment should, at the very least, explain and focus on what is special in the block of code. A very good comment also explain why it is being done.

* The best comments explain the what and the why succinctly.

* How to comment
1. Ask yourself "What?"
2. Ask yourself "Why?"
3. Write what you would say to someone so that he could do what you have done. Use simple language. (This point intentionally abstruse, to serve as a memory-aid)
4. Review and edit what you have written, the best you can.

* Do not state the obvious! But also remember that what is obvious to you may not be obvious to another person. It's a thin line between advising and preaching.
Code like:
x=0; // Assigning the value 0 to the variable x
is a big no-no. Do not insult the intelligence of the reader. Plus, you'll have to scroll more while editing the code!

Coding Nirvana - Cryptic Mystic Droppings

CRYPTIC MYSTIC DROPPINGS
FROM THE ELEVATED STATE
OF CODING NIRVANA

1. Code is just symbols.

2. Code needs a Thread of Life to achieve its Purpose.

3. It's all about the data.

4. It's all virtual. It can be faked but it doesn't really matter; it isn't really matter anyway.

More on each of these droppings (shit!) later.

Coding Nirvana - Four Noble Truths

CRYPTIC MYSTIC DROPPINGS
FROM THE ELEVATED STATE
OF CODING NIRVANA

-----------------------------------------------------------
FOUR NOBLE TRUTHS
-----------------------------------------------------------
1. There is suffering
2. There is a cause of suffering. The cause is "Copy-paste"
3. There is the cessation of suffering - "Abstraction Of Commonality"
4. There is a way leading to the cessation of suffering — the Noble Eightfold Path

------------------------------------------------------------

"Copy-paste is the root cause of all programming suffering. Copy-paste is evil. The Eternal Conflict is between copy-paste and the Abstraction of Commonality."
- The Virtual Mystic