Date: Wed, 16 Nov 2005 13:36:13 +0000 (GMT) From: Robert Watson <rwatson@FreeBSD.org> To: Clark Gaylord <gaylord@dirtcheapemail.com> Cc: freebsd-net@freebsd.org, Jon <comepu@gmail.com> Subject: Re: hello, everyone , i have another question Message-ID: <20051116133045.U9390@fledge.watson.org> In-Reply-To: <437B174B.1050405@dirtcheapemail.com> References: <002e01c5ea94$35f05750$ba00a8c0@wtfzhangj> <437B174B.1050405@dirtcheapemail.com>
next in thread | previous in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20051116133045.U9390>