5.2 Commenting Your Work

See Comments.

Sometimes, code is published while it is known to be suboptimal in one way or the other. Maintainers use various ways for leaving a trace that will later bring their attention to such code sections, usually in form of some special string they can search for, and which is generally included in comments. The `/* FIXME:... */' comment habit comes from some other GNU package (maybe gcc or gdb?), using this precise string (`FIXME' written in capitals, and immediately followed by a colon) uniformly among Gnits packages makes it more easy to interpret such comments in our code, or write tools retrieving or recognizing such comments. Moreover, using `FIXME:' strings is not limited to C code. This should be extended to shell or m4 scripts, Makefiles, and even documentation, using for each the commenting device which is appropriate.

In a word, not only should we use such `FIXME:' strings to introduce comments about suboptimal code, but we should be careful at saving such comments in the code when they come to our mind, for the benefit of those reading the code and willing to further contribute to code maintenance. An alternative is maintaining one or more TODO files, which may be good for generic or global points in maintenance. For specific points in code, `FIXME:' strings kept right where they belong, are more useful.