In this Meditation I provide an overview of literate programming(LP)
with perl. In the interest of not being too wordy I will omit much discussion
of the theory of literate programming. There is an excellent article
here by Mark-Jason Dominus
which discusses literate programming in some detail. By not belaboring the more theoretical points
what remains here is essentially a quickstart guide in LP using the perlWEB tool. Hopefully, with a short and practical
introduction to LP the use of the technique may find some more widespread use. My goal with this Meditation is to remove the initial barrier to entry
to using perlWEB. I found getting my first working example off the ground and to understand the main points of the tool
took me longer than I would have liked!
LP is basically a method of writing code in which you write documentation and code in the same
file(s). I became drawn to LP as I realized that it greatly reduced the amount of time I would later spend
either re-educating myself about some old code of my own or explaining my code to later maintainers.
Even with well written comments within the source files I found that LP provided so much more breadth and depth of
information that the greater up front time investment was always well worth it.
Here I will create a file based on the code posted to this node.
This has the benefit of providing a concise example that displays many features of LP with perlWEB
but has the drawback of not impressing you, the reader, with how much easier your life will be in maintaining and
updating a significant codebase. Also, as with all well intentioned examples it is a little convoluted for the sake of
exposition.
#*A small script to check the sum of a number's digits recursively
(until single digit of length).
#p This unnamed module begins the perl source.
use strict;
use warnings;
#<Main Program#>
#<subroutine to sum the digits recursively#>
# The Main Program.
Here we define the main program.
We declare a variable, |$total1|, to handle
the value returned from the subroutine |sub1|. In this
example version of the program we are only going to
exam the number 1818 to demonstrate
that we get the correct result of 9. If we do get this
result than we |print| a confirmation. Note also the use
of |perlWEB|'s macro ability.
#d TEST_NUMBER=1818
#<Main Program#>=
my $tota11;
for my $num (TEST_NUMBER..TEST_NUMBER){
my $tota11 = &spl($num);
print "$num == 9\n" if ($tota11 == 9);
}
# The subroutine that handles all of the essential computation.
The algorithm is as follows:<br>
• |$total|=the sum of the digits of what is
expected to be the sole(or first) argument to |sp1|<br>
• if |$total| has 1 digit then print it out<br>
otherwise…<br>
• call |sp1| again with |$total| as the argument
#<subroutine to sum the digits recursively#>=
sub spl{
my ($num1) =@_; #we can still have inline comments as well.
my $total = 0;
$total = $total + $_ for (split '', $num1);#here $total is
#the sum of all the digits of $num1
my $len = length ($total);
return $total if ($len == 1);
&spl($total) if ($len != 1);
}
If the above code is in a file called example.w then the command w2h example.w -o example.html
will create the documentation file that looks like this. Nice, isn't it! Imagine giving that
to the developer responsible for maintaining your code! This is the sort of document I wish I started each job with!
The process of creating that documentation from the LP source file is called WEAVE-ing.
Now, to create the perl source file(TANGLE-ing) for the interpreter to actually run we need to use the command
w2p example.w -o example.pl
Here is what example.pl will look like:
use strict;
use warnings;
my $tota11;
for my $num (1818..1818){
my $tota11 = &spl($num);
print "$num == 9\n" if ($tota11 == 9);
}
sub spl{
my ($num1) =@_; #we can still have inline comments as well.
my $total = 0;
$total = $total + $_ for (split '', $num1);#here $total is the
#sum of all the digits of $num1
my $len = length ($total);
return $total if ($len == 1);
&spl($total) if ($len != 1);
}
The perlWEB documentation covers the full process of how the source file is assembled. Please do refer to
it when you get a chance but for now we need only concern ourselves with a few key points:
• The perlWEB source file has a number of sections. • The starred sections are major headings and we only have one.
Most sections have a name but there may be any number of unnamed sections. • Unnamed sections are the sections that
begin with #p. There must be at least one unnamed section. I find it convenient to put it right in the beginning.
• At several points raw html is added to enhance the readability of the documentation.
Here is what I left out:
• change files
• file includes
• … and a ton of fiddly details. My goal here is to give a quickstart guide for the impatient but yet still diligent perl developer.
I am not trying to re-write he perlWEB manual but simply try and make it more accessible.
Some final notes that I recorded while writing this:
0. I have been informed that he book Elements of Programming with Perl discusses literate
programming with perl in Chapter 9. I do not own this book nor
have I ever read the text itself. I have read excerpts on Amazon.com
and have looked at the freely downloadable source
code.
From the author's file pqtangle.pdf it appears he discusses a system
developed in the text that uses a syntax similar to noweb. noweb
is a language agnostic literate programming tool which has many merits.
However, for the purposes of this article I have focused on perlWEB. The main
reason for this is that unlike noweb and many other literate programming
tools perlWEB's weave output is in html as opposed to TeX or LaTeX and I
believe that html is much more accessible for the majority of working
developers than TeX or LaTeX. When one sees that most literate programming
adherents are Math and Computer Science academics I think it lends credibility to the
argument that the hurdle of learning TeX or LaTeX is sufficient to
discourage more widespread adoption of these techniques.
1. At the first run of w2p I get the following error:
$ ./w2p temp.w
./w2p: line 29: /usr/lib/cpp: No such file or directory
If you have this problem the fix is easy...
This is fixed by usingthe right path. On my machine the correct
path is /usr/bin/cpp. perlWEB uses the C pre-processor for macro definitions.
2. Some users may be put off at the age of perlWEB. Please don't be!
While originally written in 1997 they system is very stable and is
holding up quite well.
Here is the link for the perlWEB homepage.
|
Re: An Introduction to Literate Programming with perlWEB
by BrowserUk (Patriarch) on Jan 13, 2009 at 10:25 UTC
|
Knuth's concept of Literate Programming (LP) has been around since he published his paper in 1984. (Auspicious year!)
If it is such a good idea, how come that after 28 years, there are so few examples of real-world use?
Short answer: Because most programmers are not writing code for use as examples in books or academic papers,
nor do they seek the understanding of those illiterate in the (programming) language of choice the code is written in.
Longer answers (not necessarily in order of importance or frustration factor!):
- As a programmer, I am mentally incapable of--untangling, or is it unweaving? Maybe I'll stick with--rearranging the snippets of code littered (or maybe literated?) amongst large volumes of meaningless English prose.
It's meaningless because: the compiler won't compile it; the interpreter won't interpret it;
and nothing on earth will test it!
- Neither the veracity of the claims it makes;
- Nor the correctness of the algorithms it describes;
- Nor the accuracy of correspondence between the prose and the code it purports to document.
- Instead of one level of maintenance, we have SIX! Six you say? Two surely? No! Six!!
- We have the English to maintain:
Is the phraseology clear? Are there no deceptive misspellings? No ambiguous punctuation?
- We have the algorithms and logic that the English describes to maintain.
Are the correct algorithms used? Is the logic, logical?
- We have the source code to maintain--in all the usual ways.
- We also have to ensure that the English description correctly describes the chosen algorithms.
- We have to ensure that the code actually implements the algorithms described, as described.
- And we have to make sure that the prose remains attached (physically adjacent to and above) the code it is describing.
And when it comes time to re-factor a portion of one of the code snippets, that we move the appropriate subsections of the
the original description to where ever the refactoring takes that portion of code.
Six times as many ways to cock up, and none of the unnecessary five will likely ever have any automation tools that can be applied to them.
At least, it's very unlikely in the working careers of anyone currently earning a living as a programmer.
- It adds another layer between the product of the programmer: the source code; and the consumer of that product: the compiler or interpreter.
If you doubt that is a problem consider: Will compiler detected errors be reported in terms of their LP form line numbers or their post-processed form line numbers?
If you've used Inline::C (or any Inline::* language), they'll you'll undoubtedly be familiar with the game:
- Write code
- Attempt a run
- Compiler detects an error--lists the erroneous line number in yourfile_dead.xs(69)
- Navigate to ./_Inline/build/yourFile_dead_pl/yourFile_dead.pl But it's not there!
- Go back and add CLEAN_AFTER_BUILD => 0. Re-run.
- Compiler detects an error--lists the erroneous line number in yourfile_beef.xs(69)
- Navigate ./_Inline/build/yourFile_beef_pl/yourFile_beef.xs Load it into your editor.
- Examine line 69;, relate it to the error message; think for a bit; see what you think is the cause and correct it. Save file. Re-run.
- Compiler detects THE EXACT SAME error--lists the erroneous line number in yourfile_abcd.xs(69)
- Doh! Go back to the source (*.pl* file), work out which line in that file is the source for line 69 in the .xs file, Make the change (again!). Re-run.
- Compiler detects a different error--lists the erroneous line number in yourfile_a9c7.xs(73)
- Switch back to the editor, switch back to the .xs file. Line 73 *IS A BLANK LINE!*.
Doh! This ./_Inline/build/yourFile_dead_pl/yourFile_beef.xs Discard it!
- Navigate to ./_Inline/build/ ... which bloody suffix was the latest?
- Switch to other shell: Ah! A9c7
- Navigate to ./_Inline/build/yourFile_a9c7_pl/yourFile_a9c7.xs; load file to editor. What was that damn line number again?
- Examine line 73, relate it to the error message; think for a bit; see what you think is the cause and correct it. Save file. Re-run.
- Compiler detects THE EXACT SAME error--lists the erroneous line number in yourfile_abcd.xs(73)
*********AAAAAAAAAAAAAAAAAAARRRRRRRRRRRRGGGGGGGGG!!!!!!!!!!!!!**********
- Pre-processors and textual substitutions are evil. (And I don't say that about many things!)
To see the point at its extreme consider the readmore in Re^3: WIN32-API Purgetory.
Those 4000 lines of unintelligible code, manually extracted from amongst 26,000 lines filtered from a file containing 114,000 lines,
are the result of applying a pre-processor to just 785 lines of source code input.
If you want easy maintenance?
Polluting the programmers primary workspace, in the ratio of 3 or 4 lines of noise to every line of productive code;
and re-ordering the useful bits in some arbitrary fashion; using textual substitutions to further obfuscate things;
and then adding another layer of indirection between what the programmer writes and the processor attempts to run
--there are already too many levels--is not the right way to go about it.
- Application, program and library documentation has a different purpose and should be separate from source code.
Architects do not record their stress and strain calculations, or materials assessment tests
on either their blue prints, or on the side of the building and bridges the design.
Or consider your lawyer presenting you with legal documents liberally strewn with footnotes and margin annotations of the form:
++Consider the term habeas corpus and the clarification of that term as laid out in Simpson v. Flanders (1999) and its
the subsequent refinement in Itchy v. Scratchy (2001)
- Production source code in not the place to educate new programmers; nor document design decisions; nor record board meeting deliberations.
The programmers job is to write programs--not teach newbies how to program. There are schools and courses for that.
If you've any musical ability (I've none), then maybe this will convince you.
Imagine your average orchestra musician sitting down to a score like this:
At the start of this piece the mood is melancholic. Don't be too s
+trident.
If you're playing the piano, press that "quiet pedal" a lot.
If you're the tympanist, use your left hand to dampen the ketties
+for the first few bars.
Violins, blur the transitions between strings and 'bend' from note
+ to note.
===== ...
==*== ...
----*-...
In these few bars, we start to get the sense of something awaking.
+
Piano, use the "soft pedal" less and less from beginning to the en
+d of the passage,
Toward the end, add the "loud pedal" on occasional sharps and flat
+s.
The kettles should be allowed to ring a little; and little more as
+ the passage progresses.
Violins: Slowly clean up you transitions and blur them less and le
+ss.
=
=
-
Bassists: This is your regular rhythm to be maintained throughout
+the piece:
=
=
-
But there are two variations on this which you alternate between
for the first two bars at the start of every other stanza--after t
+he first four--
and for the last two bars of the alternate stanzas.
= ... = ...
= ... = ...
- ... - ...
- Programmers write programs in programming languages, not just because it is easier to write
translators (compilers and interpreters) for them.
But also because their restricted syntax makes it easier to write correct, unambiguous and verifiable descriptions of algorithms.
Neither English, nor any other natural language is a suitable substitute. And I'll stick my neck out and say: and never will be.
And the idea that writing code twice--once in the computer language; and a second time in an unverifiable, inherently ambiguous,
infinitely variable of style--will some how render programs more reliable doesn't hold water.
| [reply]
[d/l]
[select] |
|
|
I can second this. I used LP techniques using FunnelWeb on a project in the past, and due to a learning curve with LP, the issues related to not using LP all of the time, and, at least for someone who has been writing code (not necessarily professionally) for over 20 years, just being "not natural", the cost associated with the initial write and now maintenance has made me determine that the next time I need to touch that code that I am rewriting it in more of a "classical" style.
I much prefer something along the lines of NaturalDocs for helping me with my documentation (although I wish that it integrated more fully with POD - perhaps the newer versions do), and more of a classical approach to coding structure.
One thing that really turned me off to FunnelWeb's implementation of LP, and LP in general (perhaps too broad of a brush, perhaps not), was changing, from the programmers perspective, the edit, execute, repeat cycle and replacing it with an edit, compile, execute, repeat cycle. Adding that extra step increased development time somewhat, and hassle significantly.
In certain domains, LP may be the right tool, and while there were some nice things from using LP, but I will need someone else to convince me that it is worth trying it again, since the use of LP was a net loss in productivity, at least in the situation I used it.
| [reply] |
|
|
Not sure how long does it take FunnelWeb to "compile" a file, but quite likely you could create a daemon/service that'd watch the source directories and compile the modified files automatically as soon as they are saved.
We use something like that for i18n.
| [reply] |
|
|
|
|
| [reply] |
|
|
Architects don't design bridges; civil engineers do.
Tell that to the architect Norman Foster who designed the The Millau Viaduct (in conjunction with a French Structural Engineer).
Stress calculation are obviously done, and checked and recorded and are an integral part of the overall design and documentation--but they don't do the calculations on the backs (or fronts) of the blue-prints. You don't put the two in the same document.
And while the contract you sign may not have all those lovely footnotes,
Exactly! You don't put them all in one document.
I strongly support project documentation--what files, modules and libraries exist (and where), and what they do; the names of the public interfaces and their parameters; and their purpose--but you don't need to include the names of the internal variables, constants or explain how sort works.
It's all about not mixing different concerns together; Not repeating effort (the DRY principle); and not creating unnecessary artificial dependencies (the decoupling principle).
Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error.
"Science is about questioning the status quo. Questioning authority".
In the absence of evidence, opinion is indistinguishable from prejudice.
| [reply] |
|
|
|
|
|
|
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.
| [reply] |
|
|
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
Oh, but it does!
When writing documentation in a different file, people are far less tempted to start describing how the code works--opens a file; increments a variable; sorts an array; stuff which all but the most novice of programmers can (and if they are to do a descent job of maintenance work; should), work out for themselves, from the code.
Instead, they (should) concentrate on:
- the what: the public APIs and their parameters;
- the why: their function and purpose, in terms of what they are intended to do on behalf of the calling code;
- the usage: this one is far to often glossed over or omitted completely.
- the contract of that API: its requirements of the caller, and promises to them.
Documentation is for users; and should be written at the same level of abstraction that the user will use the exported api.
The code is description of the actual algorithms used and their implementation. And should be the only such description. It cares not for the external abstraction.
You should be able to re-implement the internals of an published (documented) API, using different internal algorithms, or even a different language, and the documentation should not need to be change at all. Nothing in the documentation should need to change, when the implementation changes, provided that the published API is maintained.
The purpose of comments is to annotate the code with additional (brief) information, pertinent to that code, that the language does not allow to be conveyed easily by the code itself. It should not repeat the code; nor the documentation; nor the language manuals.
Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error.
"Science is about questioning the status quo. Questioning authority".
In the absence of evidence, opinion is indistinguishable from prejudice.
| [reply] |
|
|
|
|
| |
|
If you go so far as to say that you don't want to work with programmers who can talk about self-documenting code with a straight face, then you are going to pass up working with a lot of good people. Like me.
On the subject of documentation and code, I am a big believer in limiting what you document about your code. That does not mean eliminating documentation! But my attitude is that documentation exists for people who do not need to read my code, which in practice means that the public API and important data structures (particularly database tables) need to be documented, and sometimes you need an introductory document or three. What documentation does not exist for is helping people to understand my code. If I need that then I have at least one problem, and if I use documentation to solve it then I have just added another.
By reducing the amount I document, I avoid a lot of potential mistakes. Furthermore things that I think should be documented, like APIs, are things that you shouldn't be changing in your code without thinking through potential impacts anyways. So asking a person to go and document those changes makes perfect sense. If you stay consistent about what gets documented, when, then in my experience maintaining that documentation isn't too big a deal no matter where it is. And I personally find that documentation to be more readable and consistent when it is kept in one place.
Even so, documentation will be less reliable than code. But by limiting where I make my mistakes, I know to focus on those potential problem areas. This compensates reasonably well. Since I only need to maintain that vigilance some of the time, it is easier than if I had to think about it more often.
| [reply] |
|
|
I will address your points:
(1) and (2) sound like personal problems. LP does require different thought processes but this doesn't take too much extra effort. Really no more extra effort than, say, switching between perl and SQL when working on a database problem. Or switching between perl and html when working on a website.
(3) is a rant against Inline::C. These problems don't exist for me as a practitioner of LP.
(4) is a rant against pre-processors in general. I don't think anyone will argue that the extreme example you cited is good nor that heavy use of a pre-processor is wise. pre-processors have their place...I'll just say that the use of pre-processors should be dictated by your inhouse coding style and leave it at that.
(5) The architect example is maybe a little weird. I have no knowledge of architecture and so have no way to dispute your example as being appropriate or not.
(6) is an attempt at making some point but if you view what you wrote as "Literate Music" source and were able to extract out and seperate the score from the notes then, well, I really don't see anything that outrageous.
(7) Doesn't make sense. LP is not about writing software in English but putting the English in with your code. What is output is well formatted English and, ultimately, more maintainable code. You seem to want to create a strawman of "English is not a programming language"?
| [reply] |
|
|
You've either failed to read the post, or are just being deliberately obtuse in order to dismiss it.
The only one I'l come back at you on is 7: If the interleaved prose is not a secondary attempt to explain the algorithms and operations of the code it interleaves, why it is interleaved?
If it isn't an attempt to re-describe the code--and both your example and those in Knuth's original paper show otherwise--then there is no logic at all in keeping with the code, let alone interleaving it.
And the answer of course is that it is an attempt to describe the code. And syntax, used to describe algorithms, is programming by any other name. So now you have two descriptions of the same thing.
- One in a specifically designed, targetted, concise and precise language with clearly defined syntax and semantics.
- The other, a never designed, always changing, variably written, spoken and interpeted, verbose, imprecise language with capricious syntax and multiple semantics.
And both need to be maintained and synchronised.
Maybe if you are writing a book or academic paper, there is some merit, but for production code...it simply does not make sense. To me at least, but whatever floats your boat.
I will say that having been there and done that--and in a much less intrucive form; no reordering or pre-processing--it was a nightmare to both write and maintain. And that was with the benefit of a folding editor that would hide the verbiage at a keystroke.
By way of example, you're in there fixing a bug. Do you fix the prose or the code first?
- If you do both, and then the code fix fails, you have to undo both.
- If you fix the code first, where's the incentive to go back and fix the prose?
- And if you fix the prose first--there;s no way to verify it.
Any way you look at it, it's simply extra work for little or no gain.
Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error.
"Science is about questioning the status quo. Questioning authority".
In the absence of evidence, opinion is indistinguishable from prejudice.
| [reply] |
|
|
|
|
| A reply falls below the community's threshold of quality. You may see it by logging in.
| A reply falls below the community's threshold of quality. You may see it by logging in.
| A reply falls below the community's threshold of quality. You may see it by logging in. |
Re: An Introduction to Literate Programming with perlWEB
by gwadej (Chaplain) on Jan 13, 2009 at 16:06 UTC
|
Like many programmers, I tried out Literate Programming because Knuth seemed to like it. I read the book, I tried the tools... and it never worked for me.
Many years later, I saw an analysis of why literate programming never caught on (I need to find the reference). The analysis could be summed up in three points.
- A finite number of people can write code well
- A finite number of people can write prose well
- Literate programming is only useful for the intersection of those two sets.
Despite more than a decade learning to write more understandable code and better prose, I've never reached the point of being able to do both simultaneously well enough to be worth the other overhead of literate programming.
But, then again, maybe this old dog just can't learn a new trick.<shrug/>
| [reply] |
|
|
| [reply] |
|
|
I can't agree.
I don't feel like I write English very well, but I consider myself a decent programmer. I've known quite a few programmers who could write very readable code, but their prose was an absolute mess.
But, different people have different experience.
| [reply] |
Re: An Introduction to Literate Programming with perlWEB
by FunkyMonk (Chancellor) on Jan 13, 2009 at 16:51 UTC
|
Just to highlight one of BrowserUK's points about duplication causing errors, your code has a subroutine called spl (L) but your documentation refers to a subroutine called sp1 (one).
#<sp1#>
versus
sub spl{
I think this is known as an "own goal" :-) | [reply]
[d/l]
[select] |
|
|
The module name need not match the name of the subroutine. There is no "error" nor is there any "duplication". By seperating the subroutine into a named section is not duplicatng it but, rather, giving it more descriptive value. I will admit that I can see the point of your confusion though.
I have renamed the module to be more descriptive.
| [reply] |
Re: An Introduction to Literate Programming with perlWEB
by SuicideJunkie (Vicar) on Jan 14, 2009 at 03:07 UTC
|
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.
-
Having no comments at all is one extreme end of the scale.
-
Having a full page essay for a simple function is the other extreme end of the scale.
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
| [reply] |
|
|
With that level of documentation, almost anybody could understand what the code is trying to do.
I think that is the OP's point and have no idea why anyone would want to argue that the goal of very easily understood code is a bad thing?
However the documentation is pandering to people who do not have the capability of writing code at the expense of those who do.
Dude, at any company, school, or hobby group there are going to be programmers of varying skill. You may argue for or against Literate Programming but I am inferring your argument here is that you want to jealously guard your code and not let those people be able to figure it out. People that code less well than me may well deserve explanations and mentoring and not rude dismissal, got it?
| [reply] |
|
|
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.
| [reply]
[d/l] |
Re: An Introduction to Literate Programming with perlWEB
by BrowserUk (Patriarch) on Jan 13, 2009 at 05:13 UTC
|
| [reply] |
|
|
| [reply] |
Re: An Introduction to Literate Programming with perlWEB
by JavaFan (Canon) on Jan 13, 2009 at 16:27 UTC
|
So, punctuation in the document could be one of: 1) Perl code, 2) HTML markup, 3) perlWEB markup.
On top of that, I don't see from your example what perlWEB offers that POD doesn't already do. | [reply] |
|
|
