- - This "flag" is used to indicate items that require later definition. It stands for To Be Defined (or Determined). The ensuing comment should provide more particulars.
- - This "flag" is used to indicate items that have been defined and are now awaiting implementation. It stands for Not Yet Implemented. The ensuing comment should provide more particulars.
- - This "flag" is used to indicate the existence of an explicit machine dependency in the code. Again, the ensuing comment should provide more particulars.
- - This "flag" is used to indicate the existence of a bug of some form. It should be followed immediately in the comment (on the same line) with one of the keywords incomplete, untested, or wrong, to indicate its type along with a more descriptive comment if appropriate. If none of the keywords is applicable, some other descriptive word should be used along with a more extensive comment.
This is relatively small - only 4 primary keywords, with 3 secondary.
Other example standardsare much larger.
The most comonly used such keyword is probably
- TBD or TODO
- NYI: not yet implemented
Comments such as these work best when automated.
E.g., although I hate doxygen, doxygen comments get automatically extracted, and are hence more likely to be seen and corrected.
E.g. ditto Perldoc. Again, I find perldoc makes code harder to read.
Preparing this blog, I found
"The Fine Art of Commenting",
Bernhard Spuida, 2002.
Spuida mentions several such systems, including Microsoft's C# .NET system,
where XML tags are embedded in comments.
As indicated by Spuida's title "Senior Word Wrangler",
this motivation seems to be mainly about preparing documentation.
It was fun to re-find the Indian Hill Coding Standards
Every few years I seem to go through a spate of reading of coding standards.
I think every programmer should be familiar with several, many, different coding standards.
So that he or she can pick parts that work well,
for projects that need those parts.
Brian Marick's lynx.
Hypertext embedded within the code itself.
My own hope of wiki files in the source trees,
and/or linked to from the code itself.
Programming languages using extensible notations, such as XML,
allowing arbitrary structured annotations.