Re^3: An Introduction to Literate Programming with perlWEB

[SuicideJunkie]

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.

• Naming functions accurately and specifically.
• Using explicitly named variables
• Arranging algorithms to be clear and straightforward

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.