in reply to Why programming is so much more than writing code

swngnmonk,
Perhaps you received the type of feedback you were looking for. On the other hand, you might feel like those that have replied have missed the point. This has happened to me in the past. I find that many monks spend less time reading what it is you have to say than they do on the code example you include. If you don't pick exactly the right example, things spiral out of control.

I think you might have done better by not including any code at all. I was hoping for this in fact. Your meditation seems to boil down to dragonchild's current signature:

My criteria for good software:

Cheers - L~R

Replies are listed 'Best First'.
Re^2: Why programming is so much more than writing code
by swngnmonk (Pilgrim) on May 08, 2007 at 14:22 UTC

    L~R, you nailed it. In retrospect, I shouldn't have posted the code, because everyone focused on it, which was besides the point.

    I believe self-documenting code is something of a fallacy. Yes, it was easily recognized as a sorting routine. Yes, it sorted two array references based on out-of-order selection of sub-elements within each. We could all pick up on that.

    The point I was trying to make was one about the value of taking the time to do things the right way. In this case, there's nothing explicitely wrong with the code. The problem is the fact that depending on people's ability to read code, no matter how self-documenting you make it, is a cop-out.

    Like everyone else, I look at it, and go "sure, it's a sorting routine, sorting on sub-elements of two array-refs". But immediately, I think of the following questions:

    • Why?
    • What data is actually being sorted?
    • Is this intended to sort one specific set of data structures, or is it more general?
    • Why is datat sorted in this particular order?

    And this is where I get annoyed. Because this sort sub isn't documented. Because the surrounding code isn't properly documented. Because the only documentation in this 500-line script is a couple of minor lines at the top about inputs and outputs. And in the end, this sub shouldn't even exist, because as far as I can tell, it's not being used.

    Sure, code can be self-documenting, but to a point. This "self-documenting" code now requires me to spend far more time going through the code to figure out what is going on & why than it should. A car's motor is "self-documenting" in the same fashion - sure, I can figure out where everything is & diagnose the issue eventually, but the shop manual makes my life a lot easier.

    And so, back to my original rant. It's not just about writing clean, easy-to-understand code. The 'easy-to-understand' part is not just code, it's comments. Documenation. Explanation. Motivations. I'm tired of the pseudo-macho justifications for not writing documentation. Write it. Because otherwise I'm just going to come back & drive you nuts, forcing you to explain why you wrote every last method the way you did.

[reply]

      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.

[reply]
[d/l]
        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]

      If you can't read code, you should not be modifying it! Sure, a little documentation about WHY does some function exist is often helpfull, in case of this function I do think the only needed documentation is the name. And if at all the comment about why is the data sorted this way belongs not next to this function definition, but next to its use. Though it's hard to say as this is the only thing we've seen from the code.

      Jenda
      Support Denmark!
      Defend the free world!

[reply]

In Section Meditations