Thoughts on code : Comments

My thoughts about code comments :

- code and API comments are 2 different things and should be treated differently. 

Code comments :

- most of the time "method" comments should NOT be necessary.  Code should be written using guidelines that specify long and meaningfull names to all types. Hence if the method is called GetAvailableUsers then what's the point in adding a comment like "Gets the available users"?  The method name already tells the person who's reading the code what is does.

- comments should ONLY explain the WHY (why is the code doing this thing in this way ?). We can find the HOW just by reading the code.

- comments should be added only when there is need for them. There is no point in commenting everything (most people hate "green noise" when they read code).

- some people use comments hoping to "fix" badly written/broken code. This is SOOO wrong.  Documenting a mistake will not make it better. Consider refactoring the code and removing the comment.

- comment rot is very bad. When you refactor a piece of code, DO remove the unnecessary  comments.

- do NOT create a file header (with the name of the person who created the file, creation date etc etc). These stuff can be easely inferred from source control.  

API Comments :

- code samples are much more important than comments.  It's much more simple for the API user to have a sample on how to achieve a certain thing then to try figuring for himself by reading the API comments.