Hacker News Reader

Comment by peterwwillis | Hacker News Reader

I can't really comment on code since i'm no master of C programming myself, but there are really way too many comments. It actually makes it harder to read code if there are comments on every new line, and harder still if you have multiple lines of comments to explain one line of code.

My recommendation is to have one comment to explain a large chunk of code and let the programmer discern what part is doing what instead of annotating it piece by piece.

View on HN

It is meant as a literate program: http://uggedal.github.com/going/going.c.html. (Scroll down on this page!)

It's actually a pretty nice example of the problems with overcommenting. For example, redundancy: "atexit(cleanup_children)" is perfectly self-explanatory, yet he repeats the same thing with the circumlocution "We setup our cleanup function as an exit handler which will be called at normal process termination." That's just a waste of both the writer and the reader's time.

And of course, redundancy spawns inconsistency: the code says "spawn_unquarantined_children()", but the comment says "All quarantined (a newly initialized child structure is quarantined by default) children is spawned for the first time." Which is it, quarantined or unquarantined? And the comment breaks number agreement, too.

I find it remarkably illustrative that comment rot has already set in into version 1.0 of a "359 LoC" program (actually 797, according to github).

I give him kudos for using atexit() at all; it's sorely underused.

I saw that, and I still think it's quite excessive. Perl modules often come with POD documentation in-line with code, but it's usually just to document something like a function or method with maybe an example or two. (And yes, POD is not literate programming, but it's more like the comments you'd see in a normal program source code)

I suppose this is up to the individual, but I don't like literate programming partly because it interferes with a dynamic that coders around the world have. Most people include comments only when it's necessary. It signifies something important to take note of and clarifies unusual behavior. Literate programming partly strips that away without giving you a really long-term benefit... It seems useful to me mostly for the initial implementation and ends up making maintenance a chore.

If I can modify my original comment a bit for literate programming: Make a comment at the beginning of your function with a bullet list of how the function will work, step by step, and then just write the code. Easier to read and you still have your [mostly-]literate program.

If you keep commenting like this, the metadiscussion about comments might become competitively long.

I liked the comments, not because I needed them to help understand what the program is doing (this is a bog standard C program that I think most Unix developers have written several times over) but as document of someone learning C, and as something I can show other people who want to learn C.

I'm a sub-par C programmer and the comments definitely helped me out. Instead of assuming the reader knows what each function does, they are explained in enough detail that the average reader could at least Google for more info based on keywords.

This. Having a paragraph of explanation text for each line is not a replacement for source code that is readable by itself.

I understand, though, that explaining each and every line of code was done for the sake of learning C.

This is very readable C code, as C code goes. The documentation isn't there as a substitute for that.

Agreed. Even literate programming (where the comments often outweigh the code) doesn't stop to explain #include <stdlib.h> !

Edit: ok I forgot this was his first C program.

No, but you can see from that page that if you wanted to write a simple C program as a document on how C works that the format works nicely for it.

It's his first C program. Mine were similarly prolix. Another habit I got out of after a year or so was wrapping every use of every new API in a me-friendly wrapper function. Also, of writing my own linked list code over and over again.

Literate programming tools like CWEB often have a tool (in CWEB called CTANGLE) that extracts just the machine-readable code. Perhaps there is some tool you can use to decomment this code (maybe even just grep :D)

Reply on news.ycombinator.com