Beefy Boxes and Bandwidth Generously Provided by pair Networks
Keep It Simple, Stupid

Comment on

( #3333=superdoc: print w/replies, xml ) Need Help??
Lot's of valuable considerations -- from the OP and the first reply as well. IMO, these are the key points:
mpeever: improving the clarity and brevity of code will result in much more maintainability than attempting to make it maintainable.

kyle: Sometimes "maintainability" is about "editability" rather than "readability".

By far the worst PITA for any code maintainer (whether working on one's own code or someone else's) is finding that a particular bug fix or enhancement entails making a particular change multiple times in multiple places. Resisting the false economy of copy/paste programming is a discipline that is forsaken all too often by coders in all languages.

When you take the time to actually analyze the task at hand (many of us hold the "official" job title of "programmer/analyst, and there's a reason for that), there is virtually no need for more than one instance of a given literal string, "if" condition or computation/assignment statement. People who repeatedly copy a sequence of lines and make minor changes in each copy -- instead of creating a subroutine with parameters to handle the variations -- should be employed as "data-entry technicians" rather than programmers.

As for the proper role of comments, I agree with this point completely:

Of course comments are good for some things: as a maintainer I find it's easy to figure out what code does, and hard to figure out what it's supposed to do.

My personal mantra is: no source code file that will require maintenance should ever be written before a spec is written to explain its purpose. My personal habit for obeying this law is to start each perl file with a standard POD template (NAME, SYNOPSIS, DESCRIPTION), and this gets fleshed out with a good-enough (clear and reasonably detailed) explanation of what it's for and how it's used, before writing any code beyond "use strict;" (which happens to be part of the template). In some cases, I end up with more lines of POD (and take more time to write that) than lines of code.

This is usually so that I'll understand the file six months later, but it also helps whenever someone else asks something like "what was the spec for that procedure we did six months ago?" The POD is the spec.

In reply to Re: Code Maintainability by graff
in thread Code Maintainability by mpeever

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, 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, 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.
  • Log In?

    What's my password?
    Create A New User
    and all is quiet...

    How do I use this? | Other CB clients
    Other Users?
    Others musing on the Monastery: (7)
    As of 2018-07-19 08:10 GMT
    Find Nodes?
      Voting Booth?
      It has been suggested to rename Perl 6 in order to boost its marketing potential. Which name would you prefer?

      Results (404 votes). Check out past polls.