lkml.org 
[lkml]   [1997]   [Jul]   [22]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
From
SubjectRe: Take A deep Breath - Kernel Documentation
jwalther@citytel.net writes:
> So would the boss chew out the programmer? Yeah, but thats their job.
> They'd do it no matter if the code was commented well or not. Bosses only
> demand comments because they are ignorant and unskilled and frankly, feel
> inadequate because of the lack of understanding and power they have over
> what their "employees" do.

No, they chew them out because they get lots of flack from other
programmers, and they discover that it takes 6 months for new
programmers to start doing useful work on the project. Programmers do
not work in a vacuum, other programmers *will* see the code, and
*will* have to modify parts of it. If the "boss" is a programmer
himself (ie, a project lead, not a manager), that boss will notice the
problems himself without others pointing them out. And the problems
will crop up in ever code review, everytime the programmer takes a
vacation, etc.

It's basic common sense; don't have a long file with ZERO comments in
it. Some of the linux files are ok, some are attrocious. Some of the
comments are aggravating with their lack of information (I saw one
that said something like "oops, forgot to do this", but no indication
of why it was needed). Mm/mprotect.c has 1 comment, that it's
copyrighted by Linus. In the same directory, and filemap.c has tons
more comments, of an appropriate nature.

And probably the simplest device driver, and one very likely to be
read by people wishing to learn about device drivers, mem.c,
doesn't have enough comments to allow someone to figure it out.
(of course, that's simple enough for people other than the developer
to comment)

> Basically, the kernel is just fine, and the programming methodology is
> *effective*. Either demontrate some large gains in productivity from such
> commenting... Or drop the topic ;)

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. Even when I look at my own code, it can be
baffling several months later without the comments. I have experience
with myself gaining productivity by looking at comments in my own
code, and I've lost productivity when I've asked coworkers what a
particular piece of code does and they couldn't remember. It helps
me pick up my train of thought when I start working the next day
or come back from lunch. That's all the "demonstration" I have, but
I'm sure others have similar experiences.

The big problem is that I think many programmers do not learn to
comment, or learn that it's something you do just before you turn in
an assignment. They never get into the habit. Myself, I can put in a
comment while sitting thinking "hmm" between bursts of typing. (and I
find it helps me write better code, since I have to be thinking
coherently about what the code does to write a comment) It takes
very little time, more time is wasted trying to defend why one
shouldn't have to comment.


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