Messages in this thread | | | Date | Tue, 22 Jul 1997 18:43:10 -0700 (PDT) | From | Darin Johnson <> | Subject | Re: 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.
| |