hello, everyone , i have another question

[Robert Watson]

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