Re: [PATCH 1/2] staging: r8712u: Most return-values changed from -1 to proper errno macros.

[Ali Bahar <ali@internetdog.org>]

Hi Kalle,


On Sat, Jul 16, 2011 at 12:23:42PM +0300, Kalle Valo wrote:
> Ali Bahar <ali@internetdog.org> writes:
> 
> > I am aware of the current state of the Linux code's documentation.
> > Habitually, I comment the big-picture as I go along. Industry
> > practice wrt comments differs from Linux's, of course. The comments
> > were in the function heads, not in the bodies, as per
> > Documentation/CodingStyle. The big-picture of the functions is clear
> > once you are familiar enough to begin to modify the code. However,
> > and especially for linux, code is read a thousand times for every
> > time it is written. Most eyeballs could do with a line or two of
> > explanation. To me, Documentation/kernel-docs.txt echoed the need
> > for a big-picture view. 
> 
> The problem with comments is that they quickly get out of date

Oh boy! I did say I don't want to start a debate, but only to explain
my original intentions. Never the less, I thank you for your response.
It suffices to say that we are mostly in agreement. Key is that my
statements were _not_ about in-body documentation.




> the actual code. So there needs to be a trade-off and in Linux it has
> been that code should be of good quality so that it's easy to read for
> everyone but there will be less comments.

My stance is that, if I were to ever argue otherwise, I should first
dig thru lkml archives for past discussions -- which is only one of
the reason why I don't debate this. :-)


> Kalle Valo

thanks,
ali