The Design of Software (CLOSED)

A public forum for discussing the design of software, from the user interface to the code architecture. Now closed.

The "Design of Software" discussion group has been merged with the main Joel on Software discussion group.

The archives will remain online indefinitely.

Self Documenting Code and other Myths

I would like to state for the record that anyone who strictly adheres to the philosophy of Self Documenting Code, to the point of not fully commenting their own creation, has been writing too much html.

Forget the next guy who comes along and has to decipher the maze of code you've created.  If you are working on a project large enough that you don't look at a class for several months, you'll curse the day you went to EJB training and got the Self Documenting Code pitch from a guy who couldn't hack it in management and was doing the training tour while waiting for his pension to kick in.  SDC is an apperition.

BTW, never write software for a salary unless your boss, your bosses boss, and the man upstairs were all x-coders forced into management and still bitter about fidling with schedules all day and pining after your job.  If someone wants some horror stories about misundermanagement, get me started on Lockheed Martin.  You guy's seen "Enron: The Smartest Guys in the Room" ?  It's like that, only Ken Lay thinks that everyone else has got things under control.

Anyone else figure that I'm going to end up on the Home Land Security watch list after this?
Jason Hitchings Send private email
Friday, August 19, 2005
 
 
Read the Python or FLTK source code.

Very little comments; Yet, very easy to read and understand a large to huge codebase.

It _is_ possible to write self documenting code, but most people can't. Very much like good design, for that matter.
Ori Berger
Friday, August 19, 2005
 
 
Good programmers comment their code.

Great programmers provide comments as to why a particular implementation was chosen.

Master programmers provide comments as to why other implementations were rejected.
Former COBOL Programmer
Friday, August 19, 2005
 
 
My code is more or less self-documenting, since I try to make it comprehensible and it doesn't have many comments. I've been working on the same code base for 4 1/2 years, and the scarcity of comments hasn't cause me any problems.

Still, had I written more copious comments, whoever ends up inheriting my code would be better off. Unfortunately, I've always had higher priority tasks to work on. It would be nice to have a job where I could compete all deliverables while writing thorough comments, but I've never been in that situation.
Julian
Friday, August 19, 2005
 
 
>  My code is more or less self-documenting, since I try to make it comprehensible and it doesn't have many comments.

Please post it. I have yet to see any code that's self documenting.
son of parnas
Friday, August 19, 2005
 
 
Hmm.  I thought Fred Brooks (Mythical Man-Month) idea of self-documenting code was that the documentation could be WITH the code, AS comments.

Some of the JavaDocs and PerlDocs comment extractors are approaching being useful -- but you gotta have comments in the code.  And the comments need to explain PURPOSE -- why the code does what it does -- and perhaps CONTEXT -- how the code is intended to be used.

Code without comments has lots of syntactical information, but not a whole lot of semantic information.  Thus it says what it is doing, but not why, or what was the INTENT of the programmer.

So I agree, that code without comments being usefully 'self-documenting' is not true.

Now, it may be possible to include sufficient comments in the code that additional design documentation is not necessary.  I doubt this strongly.  Hopefully the comments can allow you to reverse engineer some sort of design document.  I certainly have been in situations where the only documentation we had was IN the source code.  Boy, were we in trouble.
AllanL5
Friday, August 19, 2005
 
 
> Boy, were we in trouble.

Only because they didn't follow XP. If they used XP the code would be magically self documenting :-)
son of parnas
Friday, August 19, 2005
 
 
son of parnas,

What do you think of Literate Programming?

(Me, I tried to read some literate programs...)
mb Send private email
Friday, August 19, 2005
 
 
> What do you think of Literate Programming?

I found the notion of generating the program from the documentation unpleasant. The general notion though I think is a good one. I still of course use TDD and DBC, but I like to think my commenting style is the same spirit as literate programming.

Code is such a small thing. It's the ideas that are big.
son of parnas
Friday, August 19, 2005
 
 
I don't see self documenting code as a myth. I've been doing that for years. The trick as 'Former COBOL Programmer' mentioned, is making short, comprehensive and well written comments in the first place.

It's not that hard to do, especially if you do so in a disciplined manner. It not only makes it easy for myself, but for the next person down the road who inherits my code.
QADude
Friday, August 19, 2005
 
 
Thanks for the feedback, All.  In reading through the responses though, I saw a lot of: "Self Documenting Code isn't a myth, the trick is to write really good comments."

The whole raison d'etre for my ranting was that you always need comments.  No matter how nice your function names are, you can't make code simpler than it is.  Useful comments summarize what is going on and help the programmer hone in on what they are looking for without reading every line.  You'll all recall from Comp Sci that one of the fundament Axioms of Computer Science, (Indeterminancy or something), is that there is no faster way to determine what the code will do than actually running it.  You don't want to make the guy updating the code simulate the entire project in his head.

One last thought: I wouldn't consider examples of people not commenting their code as proof that code doesn't need comments. You know, we could write all of our programs in Microcode if we had a healthy dose of sadomasacism goin' on.
Jason Hitchings Send private email
Friday, August 19, 2005
 
 
I like to write the main comments for a block of code before I write the code.  It gets me to thinking about exactly what it needs to do, and helps me remember this as I write.

These comments always include what I'm doing and why, and possibly why I didn't do it in a more obvious way, if applicable, or what else I may have tried that didn't work.

The only drawback is that I need to remember to update the comments if I change something while writing.

After doing this, I generally try to make my code as self documenting as possible, usually by mudularity and carefully choosing variable names.
Marty Fried Send private email
Friday, August 19, 2005
 
 
I personally don't consider "comments in the code" as being a form of "self documentation". To me it is just another form of programmer documentation that is embedded alongside the code instead of in some other document file. The code itself is not doing any "self" documenting, it is the programmer using a shortcut or providing additional information that the code itself does not seem to provide.

Now I'm not saying that you should or shouldn't use comments. I'm just saying that people who say that code is "self documenting" are probably implying that even comments aren't needed. The actual "code" speaks for itself.

With that rant in mind, I agree with the OP: There is no such thing as "self documenting" code.
matt
Friday, August 19, 2005
 
 
I'd rather see programmers make efforts toward making code self-documenting than see them make efforts toward including more comments.  The only problem I see with self-documenting code is when you think you have it but you don't.  The way to find out is to ask other people to skim it and tell you what it does.
Kyralessa Send private email
Friday, August 19, 2005
 
 
> I'd rather see programmers make efforts toward making
> code self-documenting than see them make efforts
> toward including more comments.

Bother are necessary, neither alone is sufficient.
son of parnas
Friday, August 19, 2005
 
 
I think you will always have some comments so self documenting code is a myth (depending upon how you define it).

However I think we can all agree that having nicely readable code is a good objective for all.  But that is kind of a moving target because we all think differently.  For example I might find recursion easy to follow but others might not.

Even if all your code was written in such a way that it was immediately obvious what is happening you will still probalby need comments.  If for no other reason then to comment that you tried something and it did not work.  This kind of information gets lost even on the most well documented projects (because they change the document and then change it back).
Mark Flory Send private email
Sunday, August 21, 2005
 
 
The problem with most comments is that over time they fail to be maintained and the comments do not reflect what the code is currently doing.  Or you get cut and paste comments that are useless in the new context.  I've seen cases where comments do little but confuse matter further as the code seems to do onething and the comments explain another.
Looking for a webhost
Sunday, August 21, 2005
 
 
>The problem with most comments is that over time they fail to be maintained and the comments do not reflect what the code is currently doing.

Doctor says: don't do that. There's not a single part of software that you can't say people won't screw it up. That's not an excuse for not doing something.
son of parnas
Sunday, August 21, 2005
 
 
"Doctor says: don't do that. There's not a single part of software that you can't say people won't screw it up. That's not an excuse for not doing something. "

Not an excuse no, but reality yes.
Looking for a webhost
Sunday, August 21, 2005
 
 
By and large comments can be used for three purposes.

1. To set out the intent of a block of code or function, it might also include functional design parameters if it makes sense, ie a protocol stack or record definition if parsing.

2. To explain a functional diversion from the general logic which is not immediately explicable from the code.

3. Where the compressed syntax of the code makes the code obscure. 

In all other cases the code itself should be sufficient documentation.  However, I'd try and eliminate #3 wherever possible there are few if any gains from overly compressing the syntax even if the language allows it.
Simon Lucy Send private email
Monday, August 22, 2005
 
 
> Not an excuse no, but reality yes.

Definitely reality. But the excuse was for not writting comments. Because comments can be screwed up doesn't mean don't write comments.
son of parnas
Monday, August 22, 2005
 
 
The point the poster was probably trying to make is that a comment is not an ideal way to encode information about the program, since it doesn't automatically get updated as the program changes.

It's generally better to try and encode information in the program structure, by renaming functions, moving stuff around, trying to keep the logical structure as clear as possible as the ideas evolve.

That doesn't mean that you never need comments, of course they come in handy sometimes. But a comment is often used as a cop-out instead of organising the code more cleanly. I view heavy commenting as a danger signal that the code is not well-factored. This has been true often enough in my experience to make it a worthwhile indicator. Your milage may vary.
Matthew Morris
Tuesday, August 23, 2005
 
 
> ut a comment is often used as a cop-out instead of organising the code more cleanly.

And I would say the well named function illusion is just a cop out for not commenting.
son of parnas
Wednesday, August 24, 2005
 
 
I'm a recovering overcommentor.

Comments, like any sort of communication, is best used in moderation. Like a minimalist website (compared to a croweded website). The more comments you write, the more you dilute each one's value and the less time you have to spend on each comment.

So, I prefer fewer, higher quality comments.

These days I :

1. Use comments to document the INTENT of a function/procedure/method

2. Sparingly to explain kuldges.

3. I try to write them very very well.

4. I spend more time on refactring (better variable names, etc.) than on commenting.
Mr. Analogy {uISV} Send private email
Wednesday, August 24, 2005
 
 
What about writing small special programs whose entire purpose is to document other programs?

I have gotten into the practice of writing short programs that illustrate how to use classes I have written and how they work.  As I add features to a class, or as I write new classes, I write additional test programs to illustrate their use.  I find this form of documentation very useful and to the point.  Between that, and commenting my code itself, I generally don't write any other form of documentation.

When refactoring a class, I have to fix the test programs around the class or they will stop compiling and working (they all have to do something that can be observed, even if that is to just compile and link, successfully).  This forces me to keep this form of documentation up-to-date as the code evolves.  The source files for the test programs are mixed in with the source files they document, so a full build of one of my projects will fail if I change class A's source without the sources of the test programs that document how A works.

I have included an example of this below.  It documents a pair of C++ classes I wrote for using libpcap (the packet capture library tcpdump and many other packet sniffers use): pcap_reader and pcap_writer.

The program itself, when run, simply reads packets from a pcap stream through stdin and writes a pcap stream out through stdout.

// example_summary:  usage of pcap_reader and pcap_writer classes
// a simple stdin to stdout pcap reader/writer

#include <iostream>
#include "../pcap_reader.h"

using std::cout;
using std::cerr;
using std::endl;

using net::pcap_reader;
using net::pcap_writer;
using std::string;

int main(int argc, char **argv){
  try {
      int snaplen=3000;
      pcap_reader pr("-");
      pcap_writer pw("-",snaplen);
      while (true) {
        pr.read();
        pw.write(pr);
      }
  }
  catch (pcap_reader::open_failed){
      cerr << "read open failed" << endl;
  }
  catch (pcap_reader::end_of_pcap_file){
      cerr << "file closed normally" << endl;
  }
  catch (pcap_reader::read_error){
      cerr << "read error" << endl;
  }
  catch (pcap_writer::open_failed){
      cerr << "write open failed" << endl;
  }

  return 0;
}
Chris Marshall Send private email
Friday, August 26, 2005
 
 
Looking at the code:
1. no idea what pcap means
2. no idea what it reads or writes
3. "../pcap_reader.h" thanks for dictating the directory structure
4  snaplen - huh?
5. pcap_reader pr("-"); - huh?
6. pcap_writer pw("-",snaplen); - huh?
7. while (true) {  - how does this ever end?
8. pcap_reader::end_of_pcap_file - oh, exceptions such for normal state


In short, I do not feel in anyway illuminated.
son of parnas
Saturday, August 27, 2005
 
 
The questions you asked are all well within the common understanding of the people I work with, for whom I wrote my example program.  What they don't automatically carry around in their heads are the details of using my pcap_reader and pcap_writer classes such as which constructors you would call in which situation, which exceptions are relevant to which operations, etc.
So by writing very short programs to show exactly how they work in standard cases, I am providing them a form of documentation.

I'll grant you that my "../pcap_reader" include dictates directory structure, and that that may not always be a good idea, although in this case I think I have my reasons.  I'll also grant you that defining an exception for end-of-file might not be a good idea, although I haven't yet convinced myself of that.

My take on the issue of when to use exceptions is that it depends on what sort of details you want in the main flow of the program's logic, and that reasonable people might disagree on exactly which details should be in the main flow and which should be special cases.  Can you not conceive of a function that was manipulating several files at once where wrapping each read in a "if (read hits eof)" clause might obscure the main flow or at least complicate it beyond where the details you cared about were clear at a glance?

For the record, here are the answers to your questions:

Pcap means "packet capture". 
Libpcap is the packet capture library used by tcpdump and ethereal and many other packet sniffers.
pcap_reader is a class for reading packets from files saved in the pcap format. 
pcap_writer is a class for writing packets to a file in the pcap format.
"snaplen" is the snap length, or the size of the buffer the packets are being written into.  It is the maximum number of bytes that will be captured from the wire.
The "-" argument means to read from standard in or write to standard out.  Any other string in the same place would have referred to a file of that name.
Chris Marshall Send private email
Monday, August 29, 2005
 
 
Selfless Human Programmers and other Myths....

Comments are good for me, the programmer, because I have poor short-term memory. I rely on them to recall what the hell I was doing last week when I was coding a particular class or function. So they’re a matter of necessity since they impact the quality of my output.

These comments tend to be prone to obsolescence or undecipherable and/or irrelevant to someone who is not me. The subset of comments that do not suffer from these issues represents the sum of meaningful code documentation that I generously pass on to the unfortunate JP responsible for maintaining my code.

Is that bad?

It’s certainly not ideal. But in some (probably most, yet certainty not all) cases it follows sound economic theory. Weigh the cost of the time required to articulate readable documentation and maintain consistency with the implementation over time (not insignificant) against your deadlines and the odds that someone else will need to decipher your code (and knowing it’s YOUR code) in the short term given your unavailability.

Most environments in which I’ve produced code - and I don’t think I’m alone here - have imposed absolutely no penalty for crappy/missing comments and no rewards for excellent documentation (a short-term cost with long-term value, and therefore completely undervalued and generally ignored by management). If fact, you may risk an accusation of padding your estimates if you opt to explicitly state that a portion of your LOE represents documentation.

Completing working code on time, however, will get you noticed. The point to all this (geez look at the time I’ve wasted. I could have been producing code all this time) is that a human programmer intrinsically avoids work that is not incentivized. As with all things, I happily pass the blame up to management :)

I should note, there is one exception to exclusively self-targeting comments:

Sometimes I write code that makes me think, “oh dear, if anyone reads this and manages to understand the wickedly clever twist of logic I’ve weaved here, they will absolutely be forced to contend with the undeniable authority of my coolness.” So I write a little comment (initialized this time) next to it... not too verbose, but enough to generate some intrigue. After adequate inspection, this yields a wow moment causing the reader to burst out something similar to “holy crap, that’s genius!”. That’s how it plays out in my head.
Hans M Meyer Send private email
Wednesday, August 31, 2005
 
 
My respects to Chris Marshall:

Pcap means "packet capture".

Then call it "packet_capture"

Libpcap is the packet capture library used by tcpdump and ethereal and many other packet sniffers.

Then call it "packet_capture_library"

pcap_reader is a class for reading packets from files saved in the pcap format.

Then call it "packet_capture_reader"

pcap_writer is a class for writing packets to a file in the pcap format.

Then call it "packet_capture_writer"

"snaplen" is the snap length, or the size of the buffer the packets are being written into.  It is the maximum number of bytes that will be captured from the wire.

Then call it "packet_capture_buffer_max_length"

And what I notice from these names is a lurking class of it's own called:

PacketCapture with a couple of responsibilities.

Comments in code are technical writing.  There are very few good technical writers and even fewer that are good programmers also.  What I have learned to hate about comments in code is that they are usually:

1.  More poorly written than the code is
2.  Redundant.  Just restating what the code does
3.  Used as a crutch for typing in longer variable names

My favorite of the last was an example of "good commenting":

ptr : pointer;  //Pointer to input buffer

Real useful compared to calling the variable:

pointer_to_input_buffer : pointer;

When the above concerns are addressed, I enjoy comments.  But that is a rare occasion.  Otherwise, I would prefer to be spared having to delete "noise" so I can figure out what's going on.
John Elrick Send private email
Wednesday, August 31, 2005
 
 
That, to me, is excessively long variable names.

THat pcap example used quite a number of standardized
conventions, and the code is shorter, makes sense, and can be read very  quickly.

In contrast, using very long variable and function names make code tiring to write, slow to read, and somewhat harder to navigate.

I much prefer:

/* Program that outputs 'e\n' 10 times */
int main() {
 int i;
 for(i=0;i<10;i++) {
  printf("e\n");
 }
 return 0;
}

To:

/* No comments */
int main() {
 int index_for_for_loop;

for(index_for_for_loop=0;index_for_for_loop<10;index_for_for_loop++) {
  print_to_standard_output("e\n");
 }
 return 0;
}


In short, for variables that are used ALOT, ie 'i' for index counters, 'pcap', and so on, it is much better to use very short names that can be easily equated with what they are, and that "everyone" knows what they are, for things that are rarely used, sure, use "munge_string_escape_html(string)"
Arafangion Send private email
Monday, September 05, 2005
 
 

This topic is archived. No further replies will be accepted.

Other recent topics Other recent topics
 
Powered by FogBugz