From owner-freebsd-net@FreeBSD.ORG Wed Nov 16 13:36:15 2005 Return-Path: X-Original-To: freebsd-net@freebsd.org Delivered-To: freebsd-net@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 7107F16A41F for ; Wed, 16 Nov 2005 13:36:15 +0000 (GMT) (envelope-from rwatson@FreeBSD.org) Received: from cyrus.watson.org (cyrus.watson.org [209.31.154.42]) by mx1.FreeBSD.org (Postfix) with ESMTP id 20D0943D46 for ; Wed, 16 Nov 2005 13:36:14 +0000 (GMT) (envelope-from rwatson@FreeBSD.org) Received: from fledge.watson.org (fledge.watson.org [209.31.154.41]) by cyrus.watson.org (Postfix) with ESMTP id 0A99546B0A; Wed, 16 Nov 2005 08:36:14 -0500 (EST) Date: Wed, 16 Nov 2005 13:36:13 +0000 (GMT) From: Robert Watson X-X-Sender: robert@fledge.watson.org To: Clark Gaylord In-Reply-To: <437B174B.1050405@dirtcheapemail.com> Message-ID: <20051116133045.U9390@fledge.watson.org> References: <002e01c5ea94$35f05750$ba00a8c0@wtfzhangj> <437B174B.1050405@dirtcheapemail.com> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII; format=flowed Cc: freebsd-net@freebsd.org, Jon Subject: Re: hello, everyone , i have another question X-BeenThere: freebsd-net@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Networking and TCP/IP with FreeBSD List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 16 Nov 2005 13:36:15 -0000 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