Date: Tue, 9 Dec 1997 02:03:41 +0000 (GMT) From: Terry Lambert <tlambert@primenet.com> To: perhaps@yes.no (Eivind Eklund) Cc: mike@smith.net.au, dyson@freebsd.org, current@freebsd.org Subject: Re: VM system info Message-ID: <199712090203.TAA02842@usr05.primenet.com> In-Reply-To: <19971209013941.17444@follo.net> from "Eivind Eklund" at Dec 9, 97 01:39:41 am
next in thread | previous in thread | raw e-mail | index | archive | help
> wander far from the ultimate. Any form of documentation that is > in-line in the code is much more likely to be kept up-to-date, and it > _is_ fairly cheap. > > <GENERAL RANT> > Any attempt at making things easier for the newcomers at a slight, > indirect expense to the people 'in the know' seems to be shouted down > immedately. Leanness of the kernel and the source tree seems to have > a small but vocal minority that shout down any documentation that > might actually be kept up to date. (Ref my attempt at finding some > tolerable way to provide inline documentation for kernel file use last > easter). > </GENERAL> I'm firmly in the "if you commit it, document it" camp. HOWEVER... Inline documentation is just as bad, or worse, than non-inline documentation. I disagree with the premise that it "is much more likely to be kept up-to-date". Further, such documentation tends to obfuscate otherwise readable code with all sorts of non-code pieces, making it less likely the code will be maintained, either. I've worked places where inline documentation was supposed to have been maintained "to the benefit of all", and have seen only grief from it. In FreeBSD, where the effort is all volunteer, you can't even threaten to fire someone for not playing by the rules in order to get them to (grudgingly, at the end of the project) document the code that should have been documented and the documentation up-to-date since day one of the project. Certainly, there's room for improvement in code commenting, and there is definitely room for architectural "white papers" describing what the code is intended to implement, but writing whitepapers (or man pages) in block comments preceeding functions, etc., is just not the place for whitepapers or man pages. Inlining documentation is evil. Non-documenting is evil. And two wrongs don't make a right. IMO, of course... Terry Lambert terry@lambert.org --- Any opinions in this posting are my own and not those of my present or previous employers.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?199712090203.TAA02842>