

Document Your Code - vital101
http://www.re-cycledair.com/document-your-code

======
mcharkin
Although documentation is great, too often I have seen it get out of date,
especially the big block comments above the functions. It also becomes to
understand a big block comment, especially if the comment is too detailed,
since you have to keep jumping between parts of the code and parts of the
comment.

I like shorter high level block comments and a lot more short comments that
are directly next to the complicated parts of code it tries to explain. This
way the block comments will stay up to date, and it is easier to update a
short comment next to the specific lines of code. Since writing a short
sentence about what you have just worked on is easier than adding to a large
intimidating paragraph.

But the from my experiences, the beast practice is to write clean
understandable code that does not need comments; updating code is mandatory to
fix bugs but updating comments is an annoyance. Code reviews do marvels at
reinforcing this, especially if the reviews are done through some tool that
allows your coworkers to attach comments to specific lines of your code. This
way the people can see specific problems and learn from each other. Also the
social pressure of having your code definitely seen by others makes you write
much cleaner code, as making the same mistakes over again will make you seem
stupid.

