Code Notes
The source code has numerous "notes" and other comments that are important and have a certain format. These are special comments that are preceded by a word in uppercase, for example:
// NOTE this may change
Such comments should immediately precede any statement(s) or function they refer to. Or they may be at the beginning or end of a block if they are less specific comments.
There are several identifiers:
NOTE - Just a notice or reference; usually helpful.
TODO - A notice that something should be changed.
FIX - Similar to TODO but should be considered more important.
BUG - A known bug or issue that should be fixed.
MUST - A qualifier for other notes.
They can be combined.
These notes are in uppercase so that they can be searched for and identified more readily. For example, once a week someone can use grep to list all of the TODO notes:
grep -R -n TODO this/* this/admin.php:121:// TODO move this (it's fine here but less logical) this/display.php:42:// TODO MUST FIX NOTE document what/why this is this/error.php:99:// MUST NOTE FIX TODO this is ugly code
Secondary to this search and display feature of the notes is that we might add an automated search and display feature to the "help" module, so that the code can document itself.
Notes
1. Well, that's one of our goals — but we are a little behind schedule.
2. This is all not "invented here" by any means.