Documenting Code

There are many reasons why developers are told to document their code. As Jason Baker shows, many of these common reasons for commenting code are mythical. That is to say, the added benefit for documenting a piece of code may be misguided in certain contexts.

For instance, comments need to be updated as the code is updated. This means more in-depth maintenance for comments. Unless you strive to keep comments simple and generic enough. This is usually the best approach.

Often, the best way to document your code is to spend a short amount of time and overview your code as though you were someone else. If that person needs an explanation for some section of code, give it to them. But keep it simple.

You can still document trivial methods that are self explanatory. The best reason for doing this is consistency.