Well it seems to me that there are programmers who have trouble doing the mental context switching between "thinking in code" and "thinking in english", and they have a visceral objection to all forms of mixing code and english together (comments in code, pod embedded in code, etc.).

I'm not one of these people myself -- I'm a fan of embedded pod, and I go as far as to say you should avoid working with people who talk about "self-documenting code" with a straight-face... but on the other hand, part of the game of writing code for other people to read is to keep in mind that there are other kinds of people out there. It's not a bad idea to remember that there are "pure code" people around, and so you should do your best to keep comments brief, and so on.

The objections that the "pure code" folks have to mixing words in with your code frankly don't often make much sense to me. For example, BrowserUK likes to complain about the need to maintain code and documentation in parallel, but that problem doesn't go away if you move the docs to another file... in fact, at least in theory, keeping the docs for a sub with the sub is supposed to make it more likely the docs will be changed when the code is. (It certainly works that way for me... but then, Damien Conway claims that it doesn't seem to work in practice, so who are you going to believe?).

Some older threads on this subject, if anyone's interested: Code Maintainability, Programming *is* much more than "just writing code"..

But then, I'm afraid I must agree that pre-processors are a bad idea. I'm a fan of the perl debugger myself -- do you know what it's like to try to debug code that uses a pre-processor? The abstractions the pre-processor was used to implement break down immediately, and you end up steping through the other guys code instead of the stuff you're working on.

In general, I think perl is a very nice, flexible language, which means it can be used to implement variations of itself... but if you take that too far, it doesn't seem to me like programming in perl any more, and I lose interest pretty quickly.

In reply to Re^2: An Introduction to Literate Programming with perlWEB by doom
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.