When you write some code, what should be documented, either through the comments, a separate documentation or by using literate programming?

I personally see three important points:

  • The why: why the software is designed that way, why using this algorithm instead of another, the rationale behind a specific design, etc.
  • The global overview: giving all the clues that will help a new reader to quickly grasp your code and find his/her way through it. Some people would call it the architecture;
  • The non-obvious: make explicit things that are in your code but might only be understood after a deep fall into the code (e.g. the graph of a state machine which is encoded in a complicated way for improved efficiency, subtle race-conditions to avoid when using some locks, ...).

I am probably the first to not follow this advice. But I should! ;-)

What is your opinion?