On Wed, 16 Nov 2005, Clark Gaylord wrote:
Jon wrote:
I offten discover what such "/* XXX */ " annotate in source code of
freebsd. what mean is "XXX"?
These are "equivocation marks". They are placeholders for "I'm not sure
I want to do this and want an easy way to find it again so I can undo
it." Usually the intention is to come back and remove the equivocation
marks once the code has passed some test (like: "it compiled! yea!")
In many cases, they may be entirely vestigial, but in others the author
may have felt that the solution still wasn't right, even though it
worked, and wanted a visual clue to that effect for the reader.
It is fair to say that the probability of bonehead code is somewhat
higher in the vicinity of these marks.
I usually initial and date my equivocation marks to help myself (and
others) recognize vestiges, but this is an uncommon practice
(unfortunately). In public repositories some people won't sign to
protect themselves from embarrassment to the casual reader.
One of the unfortunate side effects of an older generation of XXX comments
in the FreeBSD kernel is that while the defect associated with the comment
was obvious to the writer, it's often nonobvious to a reader 10+ years
separated from the the time of writing. Newer ones tend to come with a
phrase or sentence identifying the nature of the problem, which helps a
lot.
There was a study a little while back on the changing number of XXX's in
the FreeBSD kernel source. While the study seemed fine, I found some of
the responses puzzling: the number of XXX's in the kernel source
corresponds to the number of known problems, which while related to the
total number of problems, cannot be simply equated with it. An increase
in the number of XXX's can mean several things:
- Introduction of more bugs, assuming rate of commenting remains the same.
- Introduction of the same number (or fewer) bugs, but an increased rate
of commenting.
- More commenting of existing bugs, discovered by readers of the source.
For instances in the latter two cases, this reflects a code improvement
rather than a reduction in quality, suggesting increased awareness of the
behavior of the code rather than more bugs being introduced. While the
5.x series involved really significant code changes in FreeBSD, and hence
likely introduced a pretty significant number of bugs, it also involved a
massive re-reading of the kernel source to identify issues that might
become more apparent with architectural changes, so a good number of added
XXX's were actually annotations of long-present bugs or issues, now
brought to light in the face of large scale analysis of the kernel.
Robert N M Watson
_______________________________________________
freebsd-net@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-net
To unsubscribe, send any mail to "[EMAIL PROTECTED]"
