All that documentation does not actually make for easily understood code per se. It does make a longwinded story that explains your code in horrifying detail, so your code should eventually be understandable even if the code is pretty bad.

The problem here is that your documentation is geared to people who don't code at all. Illiterate programming, if you will. Such people will not be looking at your code anyways!
Your target audience knows what a main function is. They know what a variable is and how to declare it. They know about loops and return. They are literate enough to read your function name and your variable names, and they have basic logical reasoning skills. (if they don't, then HR needs to be replaced)

Much like the proverbial instructions on how to remove sand, written on the bottom of a boot, I see
"Here we define the main program."
as a subtle insult to everybody capable of opening the source code to read that.


When I say I'd prefer to work at a company that bans even comments over the "literate programming" scheme (as presented here), I mean it in terms of maintaining other people's code.
People are not going to be committing Obfus to the repository, obviously. And since they're not allowed to add comments, they'll have to write cleaner code for their own protection. Say I open up a file, and start reading through the code... it is all nice until I come across: @polarCoordDrillSites = map { ... } @drillSites;
Embarrassingly I don't know about map. But the code doesn't need a comment explaining the obvious. It doesn't even need the guts of the code to explain the line! It CERTAINLY doesn't need a paragraph of english prose throwing chaff into the file.
If there is a problem with the code and I need to fix it, I will visit http://perldoc.perl.org/functions/map.html and look up the details of how map works, make sure it is working the way I think using test.pl, and presto.

On a totally unrelated note, map seems to be a lot less complicated than I had imagined all this time.

In reply to Re^3: An Introduction to Literate Programming with perlWEB by SuicideJunkie
in thread An Introduction to Literate Programming with perlWEB by adamcrussell

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.