Message-ID: <473C7C62.9030100@nortel.com>
Date: Thu, 15 Nov 2007 11:05:38 -0600
From: "Chris Friesen" <cfriesen@nortel.com>
User-Agent: Mozilla Thunderbird 1.0.2-6 (X11/20050513)
MIME-Version: 1.0
To: Michael Gerdau <mgerdau@tiscali.de>
CC: Philippe Elie <phil.el@wanadoo.fr>,
       Russell Leighton <russ@elegant-software.com>,
       LKML <linux-kernel@vger.kernel.org>
Subject: Re: OT: Does Linux have any "Perfect Code"
References: <c9d133bdb3481fbc01a572d948049f5e@elegant-software.com> <20071115082746.GA2885@zaniah> <200711151416.54570.mgerdau@tiscali.de>
In-Reply-To: <200711151416.54570.mgerdau@tiscali.de>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit
Sender: linux-kernel-owner@vger.kernel.org
Content-Length: 1157
Lines: 28

Michael Gerdau wrote:

> That having said:
> I really do like such obvious (as in: for those knowing the stuff anyway)
> comments when looking at code and probably concepts I'm not familiar with.
> 
> IMO there is no need to belittle this type of comment. IMO any casual
> reader not familiar with the whole set of functions possibly involved
> will be thankful for this type of comment - I certainly am.

Obvious comments explaining _what_ the code is doing are annoying. 
They're fluff.  You can see what the code is doing.

The critical comments are the ones that explain _why_ and _how_.  The 
comments should give the higher level view as to the rationale for that 
code.

Of course if you've got some highly-optimized bit of black magic there 
had better be some good comments explaining what's going on...but there 
should also be some comments explaining why we need the magic in the 
first place.

Chris
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/