Next: Syntactic Conventions, Previous: Formatting, Up: Writing C
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.