The sort of documentation provided in the example seems like it would be useful in a CS101 course.
However as others have mentioned, completely impractical in any realistic situation

With that level of documentation, almost anybody could understand what the code is trying to do. However the documentation is pandering to people who do not have the capability of writing code at the expense of those who do.

Documentation is a tricky thing; you must explain for those who may not be familiar with the specific thing you are doing. But you must also not hinder those who do know what they are doing. People who do not know what a main function or variable declaration is are not part of the target demographic at all.

Both cases are equally hard to understand; in one, you must puzzle out the code yourself. In the other, it is faster to puzzle out the code yourself.
However once you've figured out the code, things change...in that first case, updates are easy. In the second case, updates require writing another essay.


If I must choose one or the other, sign me up for the office that enforces no commenting! :D

In reply to Re: 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.