3 ms·

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

Camillo 14y ago
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).
- tptacek 14y ago
  I give him kudos for using atexit() at all; it's sorely underused.
peterwwillis 14y ago
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.
- tptacek 14y ago
  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.
  - azelfrath 14y ago
    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.

Camillo 14y ago

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).

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

peterwwillis 14y ago

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.

tptacek 14y ago
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.
- azelfrath 14y ago
  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.