Beefy Boxes and Bandwidth Generously Provided by pair Networks
P is for Practical
 
PerlMonks  

comment on

( #3333=superdoc: print w/replies, xml ) Need Help??
Someone commented recently that comments != documentation.

I'd like to point out that there are actually three kinds of documentation in every Perl program, each of which serves different purposes.

In essence, all programs are communicating simultaneously with three audiences:

  1. The computer, which only cares that it receives an unambiguous set of instructions in some manner: whether that's elegantly-documented programming language translated by a compiler or interpreter or binary files makes no difference to the computer. For our purposes, we're using Perl, and beyond that the computer only cares that we have a Perl interpreter; it makes no judgements beyond "this program can read that one and tell me what to do" (anthropomorphizing wildly).
  2. The user of the code, who needs to know what the program does (or is supposed to do), how to make it work, and what the program can say about errors it knows how to detect. I prefer to use POD for this.
  3. Programmers: both the original author and anyone else who'll be reading the code to try to understand what was intended and how that was intended to be done. This is the point where there tends to be a lot of argument.

One thing that programmers tend to lose sight of at times is that what they do for a living is write things that can be easily read by others and are descriptions of what they intend the machine to do. Computer languages do not confer higher efficiency to what the computer does, but are used to communicate in a pidgin that humans can understand, and that the computer can turn into runnable sets of instructions which it can execute.

The code should make the implementation of your algorithm as clear as it possibly can on its own. If for some reason (efficiency, compactness of expression, or other important reason) the code is not going to be easily read by the intended audience, then it's necessary to add the third kind of documentation, comments, to do a good job. If you intended audience is very good Perl programmers, then maybe you don't need comments.

If it's meant to be read and understood by a different audience, then you need to make it so that it is understandable to them.

All modern code is documentation of the work to be accomplished; it's simply that we have a processor that makes a portion of that documentation executable by the computer. No one faults Knuth for writing dense mathematical analysis of algorithms; if you're reading his books, that at least in part is why you are reading them. They are, however, not meant for casual programmers or beginners with little math background; those folks would be better served with a different book - which would communicate different things, yes, but which would make sense to its target audience.

"WHALE SINKS BOAT, EVERYONE DEAD" vs. Moby Dick. Yes, they communicate the same information, but the novel transmits more useful peripheral information. Comments do the same, and sometimes I find that the peripheral information - why did I decide to do this? why did I want to do this? - can be just as important as what I actually decided to do.

Depriving yourself of this important avenue of communication to both others and yourself because you think "comments are useless" is misguided.

The argument I most often hear against using comments at all is "but the comments get out of sync with the code!" - they don't "get" out of sync. Comments are part of the code. If you are responsible for maintaining the code then you are responsible for maintaining the comments as well. I completely agree that bad or misleading comments are useless. It's simply that it's your job to fix them.

  • If the code does not match the comments, fix the comments -- assuming the code is passing its tests.
  • If the code is not working, the comments may be one of the few things that tell you anything about what was intended.
  • If you make a set of comments obsolete, fix them - or if you're sure that the changes stand alone, then delete them - but only as a last resort.
  • If the comments contain anything at all about the intent of the code, you should try to correct and preserve them; a comment is a signpost of possible complexity. Unless you've mitigated that complexity in a completely transparent way for all the intended readers, keep the comments.

In reply to On comments by pemungkah

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 pondering the Monastery: (2)
    As of 2020-02-21 16:52 GMT
    Sections?
    Information?
    Find Nodes?
    Leftovers?
      Voting Booth?
      What numbers are you going to focus on primarily in 2020?










      Results (96 votes). Check out past polls.

      Notices?