Hi Kalle, On Sat, Jul 16, 2011 at 12:23:42PM +0300, Kalle Valo wrote: > Ali Bahar <ali@xxxxxxxxxxxxxxx> 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 -- To unsubscribe from this list: send the line "unsubscribe linux-wireless" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
