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:

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.

In reply to Re^2: Why programming is so much more than writing code by swngnmonk
in thread Why programming is so much more than writing code by swngnmonk

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post, it's "PerlMonks-approved HTML":


  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.