Beefy Boxes and Bandwidth Generously Provided by pair Networks
"be consistent"
 
PerlMonks  

comment on

( #3333=superdoc: print w/replies, xml ) Need Help??
I think you've muddied the waters somewhat by saying:
Documentation of code is vitally important for successful, ongoing projects, but comments are not documentation, and it has no place in source files.
If you're talking about POD here, then I think that's distinctly different to comments. POD (or JavaDoc or whatever you happen to be using) is documentation, not comments. It tells a user of a module how it's interface works. The fact that it's kept in the same file as the source code doesn't make it a comment. In fact, I think it's much better to keep it there, than some separate file that someone may not even realise is there when they're updating the code (one reason why doing this has become an industry-wide standard).

As far as actual comments go, I think you tend to find roughly 3 types:
  1. Those explaining what something does
  2. Those explaining how something does what it's supposed to do
  3. Those explaining why something does what it does
I tend to think #1 is OK in small doses. It can make code more readable, which to me trumps the synchronisation issues you're talking about. And at any rate - if kept high level enough - what a particular piece of code does isn't likely to change that much (at least without the whole block of code getting wiped or re-written, along with the comments), so it's not likely to get too out of date.

#2 is either there because whoever maintains the code is assumed to be stupid, or the code itself is obfuscated. In the latter case, the comments are really a red flag (i.e. not evil in and of themselves, but a good sign some refactoring may be needed).

#3 is often needed if the system-level design is (or has become) poor. This is true of quite a lot of the code I'm currently working with. In these cases, the ideal situation is to fix the design. However this is not always practical. This is where these comments can become useful. They shouldn't be a subsitute for system documentation, but they can make it much easier to pick up the context when reading code (and even more so if they reference system docs).

So on the whole, I don't really think extensive comments in and of themselves are evil, but they can often be pointers to other issues.

In reply to Re: Programming *is* much more than "just writing code". by Mutant
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 making s'mores by the fire in the courtyard of the Monastery: (6)
    As of 2020-10-28 00:19 GMT
    Sections?
    Information?
    Find Nodes?
    Leftovers?
      Voting Booth?
      My favourite web site is:












      Results (259 votes). Check out past polls.

      Notices?