Beefy Boxes and Bandwidth Generously Provided by pair Networks
The stupid question is the question not asked
 
PerlMonks  

comment on

( #3333=superdoc: print w/replies, xml ) Need Help??
++ for your thoughtful insights.

I dislike coming across code that is more comment than code.

I disagree though, that just because we can't be expected to make up for deficiencies in the knowledge or those that follow us in maintenance, that that is reason to comment tersely or not at all.

A programmer, especially a skilled one, can hold a great many variables in their head at once. And a programmer using a succinct language such as Perl can produce a mountain of functionality from a few lines of code - that often can't be written more clearly even if it is spread across more lines of code. A maintenance programmer coming in later will have to absorb all of the variables, and all of the logic - JUST to get an idea of what is going on in a local area. Code split into paragraphs with simple discriptive comments at the top of each paragraph are easy to digest and figure out what is going on. They are also potentially search able.

Looking at some code I wrote six months ago I came across the following "code paragraph headings:"
### check if we are in the delete grace period ### adjust check time if the last order was a renew or a transfer ### determine what the status will be if there are no errors

I was able to dive right in to what is going on with the code without reading any code. Each of those comments are around a section of code of 5 to 10 lines each that I COULD figure out if I wanted to. But I didn't have to expend the thought to do so.

Now, one important thing, is that you cannot account for programmers who lie or who comment incorrectly - but it becomes obvious quickly which comments don't correlate at all.

So I would add some additional addenda to your conclusions:

No programmer can expect to account for all maintenance programmer shortcomings, but that does not free you from the obligation to try.

More often-than-not you are the maintenance programmer.

Keep your logic in discrete logical chunks with defined purpose - defined either with a comment or in external documentation.

Some code requires no comments.

No amount of documentation (too much, too little, or just right) will ensure that the maintenance programmer will read your documentation. Use comments and documentation.

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

In reply to Re: Programming *is* much more than "just writing code". by Rhandom
in thread Programming *is* much more than "just writing code". by BrowserUk

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, 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?
    Username:
    Password:

    What's my password?
    Create A New User
    Chatterbox?
    and the web crawler heard nothing...

    How do I use this? | Other CB clients
    Other Users?
    Others romping around the Monastery: (4)
    As of 2020-10-27 21:26 GMT
    Sections?
    Information?
    Find Nodes?
    Leftovers?
      Voting Booth?
      My favourite web site is:












      Results (258 votes). Check out past polls.

      Notices?