login
Header Space

 
 

Re: OT: Does Linux have any "Perfect Code"

Score:
Previous message: [thread] [date] [author]
Next message: [thread] [date] [author]
To: Michael Gerdau <mgerdau@...>
Cc: Philippe Elie <phil.el@...>, Russell Leighton <russ@...>, LKML <linux-kernel@...>
Date: Thursday, November 15, 2007 - 11:10 am

On Thu, 15 Nov 2007, Michael Gerdau wrote:


That's the problem with really obvious comments. In the example above, 
that function had better disable kernel preemption with a name like that, 
and, assuming it's before the code begins the operation in sequence, we 
know when we're doing it. But the comment fails to explain why we need to 
disable kernel preemption before beginning the operation, just that we are 
doing so. Having the comment merely distracts the reader from the fact 
that the purpose of the code and the intention of the author are 
completely undocumented. And there's a realy chance that this comment or 
ones like it cause this statement and the place in the code where things 
would go wrong if preemption weren't disabled to not fit on the reader's 
screen together, so it is not only unclear what the author's intention 
was, but it is harder to figure out from looking at the code than it would 
be without comments, because fewer clues are actually visible at the same 
time, since each of them takes up extra screen space.

The code itself should be written to tell the reader everything there is 
to know about what it does, and the comments in code should only tell the 
reader why it does that.

	-Daniel
*This .sig left intentionally blank*
-
Previous message: [thread] [date] [author]
Next message: [thread] [date] [author]

Messages in current thread:
OT: Does Linux have any "Perfect Code", Russell Leighton, (Wed Nov 14, 9:21 pm)
Re: OT: Does Linux have any "Perfect Code", Philippe Elie, (Thu Nov 15, 4:27 am)
Re: OT: Does Linux have any "Perfect Code", Michael Gerdau, (Thu Nov 15, 9:16 am)
Re: OT: Does Linux have any "Perfect Code", Chris Friesen, (Thu Nov 15, 1:05 pm)
Re: OT: Does Linux have any "Perfect Code", Daniel Barkalow, (Thu Nov 15, 11:10 am)
Re: OT: Does Linux have any "Perfect Code", Geert Uytterhoeven, (Sat Nov 17, 4:44 am)
Re: OT: Does Linux have any "Perfect Code", Eric Dumazet, (Thu Nov 15, 2:29 am)
Re: OT: Does Linux have any "Perfect Code", Andi Kleen, (Thu Nov 15, 3:43 am)
Re: OT: Does Linux have any "Perfect Code", David Miller, (Thu Nov 15, 3:11 am)
Re: OT: Does Linux have any "Perfect Code", David Miller, (Wed Nov 14, 9:33 pm)
speck-geostationary