...or at least the way many people write it

Someone once stated that, "code should be more than write only," it should be READABLE. The author went on to suggest that style, like that outlined in the Chicago manual of style identifies document attributes to make material more easily absorbed by the reader.

(BTW if you know of the ref for that statement, please throw a ref...thx.)

Imagine no chapters, paragraphs, side bars, different size fonts, images (gee images in pod - no way huh!), one continuous monologue. Yeah Amazon, Borders, BarnesNoble would be less desirable by their stock holders!

Humans ! spend more time reading code than does the perl executable - so lets write for the most time consuming reader.

I am so tired of reading code in which my eyes, brain, and everything else has to parse the text to determine whether or not I'm looking at comments, code, pod, data, blah, blah, blah.

POD a curse (and a blessing). Pod helps compared with *roff, sgml, *tex, and all the others in being able to quickly generate accompanying documentation for a program or library. It makes it easy to have a single file contain both the code and the documentation. Compiled languages don't have this feature (hacks not included) nor do the early scripting languages.

However the ease of pod seems to be excuse to write textual elements in a file, interleaving code and documentation, in a willy nilly fashion. That is in a manner that is not quickly apparent to a human reader.

An astute reader may ask, "But why should I want to read the code - it has Pod?" That is often why I turn to the code, the Pod is a bolt-on, maybe just to pass some test, and is insufficient - at least for my poor brain.

Yep the curse of Pod, a module writer thinks, "Well if I don't get everything in the Pod, the user can always just read the code. Well for compiled languages, that was not the case, hence the docs had better be good. But now with scripted languages, gee you can always just read the code so embedded docs are simply gravy, right?

Oh and gee, what about images ! See my perlmonk writeup pod and images

If you're taking the time to read this diatribe and you have ref's to nice looking, easily readable perl code, please throw a reference.

Update

Well as you might suppose I had a bad day, reading other people's code, because of poor documentation.

Its just so frustrating...

So I apologize if I offended anyone. Perl really is a nice language, I've used it for years, which makes it even more painful when it is butchered.

In reply to Perl code - sometimes UGLY... by otto

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.