More things for the IDE (Integrated Development Environment).  Xcode is the one I use for iPhone development,  so hint, hint Apple.

Provide space to comment settings provided to the compiler by the IDE.

We can specify compiler macros and such in lots of IDEs. One example is a preprocessor flag named “DEBUG”.  Yet there may be definitions for preprocessor macros that do not explain themselves.  A deliberately bad example may be  “MAKEOBSCUREOPERATIONSALLOWED”.

If there is a place in your work where you as “why did someone do that?” then you have a need for more information.  And that information should travel with the thing it describes, not in some separate file where it may be lost (or never found).

If there is a slot to make a decision (especially a decision for another file), then there needs to be a slot to record the reason for the decision.