Re^3: Why programming is so much more than writing code

Just playing devil's advocate: I don't think it's pseudo-macho or any other kind of macho to leave comments out of code if the code in question is self-documenting by the way it's written. Good code, IMHO, is a translation layer that sits between the human and the computer, so when it's done right it doesn't require a whole lot of explanation in the form of comments. A contrived example:

  sub refuse_to_cooperate {
    my $beef_with_user = shift;
    print qq(I'm refusing to cooperate with you: $beef_with_user\n\n);
    die "Don't go away mad, just go away.";
  }


if ($username eq 'gwbush') {
  refuse_to_cooperate(qq(Spoiled momma's boys should not be given armi
+es to play with.));
}
[download]

Commenting that would add clutter without value. $beef_with_user could have been left out by simpling shifting off of @_ when needed, but then the function would have been slightly less self-documenting.

My rule of thumb: Provide POD for the interface, self-documenting code whenever possible, and comments when I'm typing before I'm truly done thinking. If I've thought my way through a thing sufficiently, then it's probably going to be self-documenting (AKA Living Documentation) when I'm done as a natural consequence.

Comment on Re^3: Why programming is so much more than writing code Download Code

Replies are listed 'Best First'.
Re^4: Why programming is so much more than writing code by Rhandom (Curate) on May 08, 2007 at 20:39 UTC
That is a nicely contrived example. The user would have to be familiar with the refuse_to_cooperate sub to know that it exits or dies. If they weren't familiar - they'd have to go and read the code for refuse_to_cooperate. A simple comment of `# dies` placed after the refuse_to_cooperate line, or a comment of `# throw error` placed before help to explain that you don't intend for any further action in this current section of code and that you'll be returning up the call stack. As much as I've observed "self-documenting" code, as it is called, is usually only self documenting to the person who wrote it. And - most code isn't contrived and easy to make self documenting. my @a=qw(random brilliant braindead); print $a[rand(@a)];	[reply] [d/l] [select]

Replies are listed 'Best First'.

Re^4: Why programming is so much more than writing code
by Rhandom (Curate) on May 08, 2007 at 20:39 UTC

# dies

# throw error

my @a=qw(random brilliant braindead); print $a[rand(@a)];

[reply]
[d/l]
[select]