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

comment on

( #3333=superdoc: print w/replies, xml ) Need Help??
Comments serve a different purpose to documentation. And documentation does not belong in source code files.

Are you talking about Perl here? Are you saying that using POD in perl code is wrong in some way? I cannot agree with that. (And just where should the documentation be?)

Okay, programming is hard, and writing proper documentation is at least as hard -- often harder: striking the right balance of natural language coherence and logical/procedural accuracy is really another form of the common tasks in programming: problem-solving, puzzle-wrestling, optimizing, getting things into the right operational sequence, working out the best way to refer to things, and so on.

(Let's face it, every higher-level programming language is really a sort of subset or reduced adaptation of a human language, designed to make control of computers possible for a wider range of humans, and easier for the ones who really understand the machines. Comparing this to mathematics, chemistry, etc, is disingenuous -- people in those fields need text books, in a human language that they know, in order to learn the symbols and the syntax for combining them. And that's a lot of work!)

So doing both the code and the documentation -- and maintaining both of them to keep them in sync -- is really hard. But that's a lousy reason for not doing it, and based on experience, I tend to believe that the code is easier to write (and to get right more quickly) when the documentation has been written first, and is as clear and unambiguous as the code needs to be. What I mean is: the coding is less work when the documentation is done first.

An added nice feature about that, when you're able to do it, is that you can show the docs to people who don't know how to program (e.g. a customer or sponsor), and assuming you are dealing with people who know how to use the same human language that you are using, they can understand it, react to it, make suggestions for improvements, and so on. Even though the population proficient in any given human language is "limited", it's a lot bigger than the population proficient in a given programming language -- English, French, etc are good for somehting, even to programmers.

And a nice thing about doing it as POD in your Perl script is that it's always right there for you, the programmer, and it's also really easy to present to others, the non-programmers, in a clear, human-readable form.

When time/money are limited, and you can only do one thing, then obviously it's better to write the code rather than the documentation. But then you get what you pay for, which is probably going to be about half of what you really need.


In reply to Re: Programming *is* much more than "just writing code". by graff
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 pondering the Monastery: (4)
    As of 2020-10-27 21:52 GMT
    Sections?
    Information?
    Find Nodes?
    Leftovers?
      Voting Booth?
      My favourite web site is:












      Results (258 votes). Check out past polls.

      Notices?