lkml.org 
[lkml]   [1997]   [Jul]   [23]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
From
SubjectRe: Take A deep Breath - Kernel Documentation
On Tue, 22 Jul 1997, Darin Johnson wrote:

> Yeah, but is it maintainable if the developers go away? The problem
> with your argument here is that it's a selfish one - the developer
> himself may be productive, and if he's selfish, that's all he cares
> about. The unselfish approach is to think about others who have to
> deal with the code.

Concrete example: a year ago I wanted to get involved in kernel
hacking, and I decided the best way to learn is start with something
simple. The console driver seemed a horrible mess, I decided to pick
it apart and clean it up as I go.

I came across two structs (vt_struct and something else, can't
remember its name now) which seemed as if they actually should have
been only one, they were always used in a 1:1 relationship.

Problem: were they split to facilitate some future enhancement to the
interface, or were they not yet merged because the original developer
never got round to it? Only the original developer would know.

A few one-line comments documenting the intention behind doing
something some or other way would really have been good, in that
situation. But I agree: the better the code, the less comments it
needs. No need to write prose.

Source code documents algorithms; comments document intentions.

,_
/_) /| /
/ i e t e r / |/ a g e l

PGP: finger pnagel@epiuse.co.za


\
 
 \ /
  Last update: 2005-03-22 13:39    [W:0.032 / U:0.400 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site