Yes, it's particularly difficult recovering from the situation where you were handed poorly-commented code. "Recovering" is about all you can do, retroactively. The solution is in working proactively when you get the chance to mold the minds of your successors.

I try to instill the following principle in new developers:

Put strategy in comments, tactics in code.

Another way to phrase this, though I think it's less strong, is "Comment why, code how." Comments should be an orientation to the general approach, not a roadmap to the use of the language and techniques used. Comments are for the maintenance programmer, who really doesn't want to STUDY your code, just surgically adjust it.

Enforcing the strategy/tactics metaphor also implies that you have to have a strategy before you can employ effective tactics. For a largish subroutine, start by coding the stub, with an English explanation of the approach to be taken. Under each line of comment, execute the tactics that will meet the strategy. Under "# Arrange unique entries", write the hash scanning and schwartian transform that achieves this aim.

Lastly, try to phrase your code so that it reads. One trick is to imagine trying to read your code aloud over the phone to someone else. Don't worry about using a few extra lines instead of a few extra clever operators. Don't hide the key conditionals that will control the routine. Be clear.

--
[ e d @ h a l l e y . c c ]

In reply to Re: No Comment by halley
in thread No Comment by awkmonk

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.