Slashdot Mirror
Literate Programming and Leo
jko9 writes "First proposed almost 20 years ago by Donald Knuth, the idea of Literate Programming is basically that of making program documentation primary, and embedding code in the documentation, rather than vice versa. Despite some obvious
advantages apparent to anyone who has struggled to understand a poorly
documented program, literate programming never really caught on.
That all could change, however, with the release of a new program called Leo,
written by Edward K. Ream.
Leo supports standard literate programming
languages like noweb and
CWEB, but with a crucial
difference - Leo adds outlines. The effect is striking: overall
organization of a program is always visible and explicit. Much of the narrative of the documentation gets placed in the outline, making documentation simpler, and allowing viewers to approach the code at various levels of detail. Screenshots and tutorials for Leo are here - if
that site gets slashdotted, you can download the visual tutorials in .chm
form or html form from Leo's
Sourceforge site. Leo is an open source program written in Python. Any current practioners of Literate Programming techniques out there? People
who have tried it and given it up? Can the addition of outlines to Literate
Programming make it more powerful / popular?"
My previous employer had a strict rule concerning code: you first write the JavaDoc for all the project, then implement it. It's useful as hell ... and if you mix that with UML design before the documentation, its a killer technique.
Life isn't like a box of chocolates. It's more like a jar of jalapenos. What you do today, might burn your ass tomorrow.
Few systems even allow multiple fonts in program text, although the original Bravo editor for the Xerox Alto did.
Did ANYONE learn (sic.) pseudo code ???
When i learned programming writing pseudo code was SUCH a big deal to the teacher that by the end of the year without even thinking i would write out the whole program in pseudo code, then, under each line of english add one line of code.
And has it ever paid off!
Now when I want to look at my own documentation, I just grep my java files and pull out all lines that begin with '//'
now when I am writing 20 pages of java code, and all my boss see's are comments I can tell him i'm am just writing Literate code!
Good day to you sir.
literate, without literate programming :)
what does leo do for me?
it looks like the oldschool windows help browser with code samples pasted into it.
I'm not trolling - I really want to understand how this makes for better code? And my employers definition of better is faster/cheaper - they could give a rats ass about structure and good documentation. They couldn't read a program design in english any better than they could in the most cryptic C syntax I can muster.
Something like this could help a beginner or student break down code and learn to think logically, but unfortunately I had to move to the 'real world'..
Sometimes I can't document something until I figure out how its going to be done.. And I figure out how to do it by writing code that works. Then I document the code.
So far this brand of rapid prototyping is the only thing that gets results fast enough to keep my bosses happy. They care not for proper technique and well-structured code and attention to detail at the design phase. 'Design' around here is no more than a vague definition of the problem to be solved. They just want it out the door.
I'm sure I'm not alone.. How does leo help me?
Yuck. Leo is a "nifty" GUI which helps you do the outline. As I comment on another thread -- we programmers like our text editors thank you very much. I am ok with a visualization program but not one which takes over my workflow.
The main.cf config file of Postfix. Without the comments it's maybe 30 lines of actual settings. With comments its 540 lines, and it's clear enough that a relative n00b like myself got it up and running in 1 hr with minimal trips to the website. Good documentation was a major factor in my picking Postfix over Sendmail. No dis to Sendmail, you understand.
There are 01 kinds of cars in the world. The General Lee, and everything else.
If your code requires massive documentation within the code to make it understandable, then your code likely needs to be rewritten.
With most languages, the code itself is ample documentation. For instance:
Person &p = Person::findPerson("Harry");
cout p.name() endl;
Is pretty self-explanatory. Anyone can tell the output of this code. It's not that programmers need more documentation, rather they need better abstraction and encapsulation (insert your favorite argument for object oriented programming here).
int func(int a);
func((b += 3, b));
When we build systems, we work directly with the client and we are able to describe the system in three equal, but very different ways. Depending on the documentation required and the target audience, we can describe the system in a way that allows everyone involved to communicate effectively. This is an advantage I don't want to lose.
From what I've read, literate programming seems to be a discipline that works best when the programmers are isolated from the client. How it works when the programmers and the client closely interact is something I simply don't understand.
No Zen is good zen
Roedy Green has written an excellent, humorous online article on writing unmaintainable code. This relates directly to Literate Programming, especially Roedy's points about maintaining existing code. He writes (here): "[the maintainence programmer] views your code through a toilet paper tube. He can only see a tiny piece of your program at a time. You want to make sure he can never get at the big picture from doing that. You want to make it as hard as possible for him to find the code he is looking for. But even more important, you want to make it as awkward as possible for him to safely ignore anything. "
Literate programming in general, and Leo in particular, would be the ultimate cure for this. It allows you to easily navigate between multiple levels of description of a program. This is critically important if you are coming fresh to an existing piece of code. You need to constantly cross-reference the high-level design and low-level implementations (and the various levels of description between these extremes).
Sailing over the event horizon
I've tried Leo in the past, and while I support the author's ideas and the idea of literate programming in general, I do not believe that the practice will become significantly more common in the near future.
There are two reasons I believe this:
1. More and more modern IDEs support the idea of folding sections of code at multiple levels. Combine this with some well placed comments, and you achieve a very high degree of readability. This nullifies the primary benefit of Leo and ensures that most developers won't ever look at literate programming tools.
2. Changing over to literate programming is, at least superficially, a large change. It's a large change because it requires that developers switch their primary environment. That's a big deal. Even if developers had the tools for literate programming in their preferred programming language already in their hands, they probably wouldn't use it.
I do hope I'm wrong about the above though. I think a shift in the industry (even for a relatively short time) to literate programming would give us new ways of thinking about systems design, development, and would greatly ease long term maintenance.
Please mod this post only if you think others should/n't read this. I have enough ego^H^H^Hkarma. Thanks!
Every compiler vendor who has sold a mainstream language compiler/IDE using a "program database" or some other such approach has tanked. (Note that I mean program database as the primary means of storing the code -- a replacement of flat files, not an addition to them.) So far, it's not really been a technological lack, it's just that programmers don't like it.
I recall reading some papers written by the major language guys a decade ago, and one of the things they all wanted to see was per-function recompilation (instead of per-translation-unit), better program information (like "where is this function used?") and other things that would require a more database-like format. Still hasn't happened except in research environments. (Pity.)
One could, but one would be a lunatic.
(I'm too tired to write it all down now, but I'll just summarize by saying that XML is not a silver bullet.)
You cannot apply a technological solution to a sociological problem. (Edwards' Law)
No, you're more than a posting newb if you think just because your house is wired with fiber that you're going to get speeds like that. Because from the nearest CO, that shit is all coax, so unless your running fiber all the way there, which can be some distance away, you're full of shit.
Finally, math books without any of that base 6 crap in them.
The biggest problem with literate programming is that most people don't write programs that are worthy of exposition. Most programs are written under extreme time constraints to solve immediate or practical problems, and their complexity arises from handling exceptions, special cases, and last minute or ill conceived extensions. Documenting these with prose actually doesn't help very much, as the prose reads pretty much as the code does: as a set of ill conceived exceptions rather than bold themes. Making the prose flow well is just work that could be used to make the code better.
If your code doesn't have these faults, then the code is already an expression of the program ideas, and one that you can excecute, so in that case literate programming techniques are needed to a much smaller degree.
There is no doubt that literate programming (like extreme programming) has its benefits, but their principal benefits are to encourage an attitude of critical evaluation to your coding efforts. This criticism is encouraged in literate programming
but not a unique feature of that approach.
There is much pleasure to be gained in useless knowledge.
Yeah, but do you honestly think you're "pulling one over" on Cox?
Finally, math books without any of that base 6 crap in them.
Hey Jack - I think your example is actually more bogus than what you are complaining about. Let me yank this one section out, and put things in perspective...
The goal of a programming language is to provide a machine with a set of instructions, not to sit down and read it a story. Do you expect your car to be made of parts which have little embedded notes explainging how they were engineered? Of course not, that's just silly
And, when you look at your compiled program, you don't see comments or documentation inside of it either. The compiler strips it out, as it should. However, when you code, you document. When a car builder designs a machine, they document it into such detail level it makes programming documentation look sparse (most of the time - I've seen it be overdone before ;-) It doesn't matter what you do, building cars, wiring offices, or programming, you better be documenting what you do - and those who don't regret it later, and lack of planning up front causes serious issues.
I probably shouldn't pick on your example - but it was a really nasty example.
Now, I don't completely disagree with your opinion that it's gimmicky, but, this provides yet another process for people to adopt if they so choose to. Any method that people feel comfortable with for software engineering or documentation that gets them to DO IT, well, sounds like a good idea to me.
Davis Ray Sickmon, Jr - looking for something to read? Check out my three free novels at MidnightRyder.org
I don't think what he has is bad, but I think there a better ways to achieve cleaner code.
Many people have mentioned that writing cleaner code is the best form of documentation. This is definitely true, unfortunately you still have people who use letter for significant variables (i.e. not loop indexes) and who don't format their code or try to do too much in one line of code.
I think a better approach to documentation is the test driven approach that is used in XP and with packages such as JUnit and Cactus. Basiclly, you write your test cases first, which will force you to pin down the exact functionality for your components. These unit tests are essenailly doecumentation on how your components should work. Granted, this doesn't document the specific code but I think that one of the reasons why so much code is hard to read is because the functionality was not clearly thought through.
I also think API documention is more important. Alot of times I am trying to use an open source package and I have a hard time understanding how to use the API to achieve certian fucntionality. I can read the code just fine but it isn't clear how to use the objects themselves.
For example, many of the core java apis are well written and well documented. If you see the HTML javadocs, you can get a pretty good idea of the class.
However, when you open the source code of the same class, it is not good looking anymore. Why? Because each method is preceded with dozens of lines of javadoc, each of which is embedded with HTML markup. That is good when the javadoc HTML pages are finally generated, but not so good when you look at the source itself. C# is worse with its XML based documentation!
When I look at the source code, I want to see the flow of the code easily. All the documentation in the source should only aid this and not hinder this. Javadoc does both. The explanation part of the javadoc can be very useful in understanding what the author's intent was when he/she wrote the method, but I am not so sure about the rest. The param, return and exception tags are no doubt useful, but often developers don't explain these very well. Plus, these are the tags that can easily become outdated.
I would prefer short and succint pieces of information documenting the code, preferrably close to the line of code that it documents.
All your favorite sites in one place!
Another idea which would work well in this respect would be altering the language used to be more reader freindly. Much C code is written whose syntax is a greater barrier to understanding the code than any concept underneath. Seperating some aspects of the language from regular syntax (such as pointer notation -- Sure, it's simple in theory, but in practice, it takes a fantastic long-term memory to remember whether you are witnessing a pointer being set to a memory address, or a value being placed into a variable without flicking around the source code or using a third party utility, which just slows you down and interrupts your thought process). Sure, an experienced coder can decipher obusficated(spelling?) code, but if the language makes it one step easier, that's a little bit of brain power to the question of "Why the hell did the original code do that?", and takes a bit away from the question "what the hell does this code do?".
It's been a long time.
One of the advantages of Literate Programming is (at least from my experinece) is that one can start with a general idea of what is needing done, and then fill down to the end, as it suits the programmer. For example, when writing a sorting routine, at some point I know I'll need code to swap the contents of two pointers. I can (in CWEB) just put a place holder in, and write it later, or, if I've got the code in my head, just write it down directly.
This method models the way that (for me at least) code is thought about. That's the key idea in LitProg - to put the source code / documentation down in a manner that models the thought processes of the programmer.
I don't have a full, firm, outline in mind right at the start. That's not to say I don't think about it - but it's not final. Using an outliner at the start would not work well with me. CWEB forces me to document the thought behind each step of the algorithm, and presents it in logical order, even though it was not written in that order.
Maybe if I had a cast in stone plan for the code before I start, I'd write better code. But I work well enough with CWEB &c that I don't see the addition of an outliner assisting.
Frankly, looking at the web page, it looks just like an outlining code editor - nothing that dramatic, and I'd rather stick to vi + CWEB.
Something I didn't put in the original notice but now regret that I left out - Leo has another new feature more difficult to describe, but that which solves the problem that several people have mentioned about not wanting to abandon an existing text editor or tool. Leo can embed an outline structure in comments, so that one programmer can work with the file in JBuilder or EMacs, and a third programmer can still work with the program(s) in Leo. In effect, Leo is a meta-text editor. When Leo opens an outline containing a file that has been edited with another editor, all of the edits are retained. This is a further extension of LP because you are getting code read back into the documentation, which means that LP techniques can be used for understanding and/or teaching existing programs. It also means that Leo allows LP to be a secondary technique to add additional structure and documentation, rather than necessarily being the primary technique. This is explained in more detail in the tutorials and Leo docs.
.NET, but this ability to separate the outline from the program is something new, as far as I know. Also, unmentioned in the original article is the idea of having clone nodes, which means your outline can put the same code section into different branches simultaneously.
It is true that there are other IDEs that allow folding, e.g. Visual Studio
The following statements will be highly inflamatory to many people. They are not intended to be inflamatory but, rather a simple observation.
Basically, Leo is yet another tool to automate the documentation of programming code. There are dozens, possibly hundreds, of programs available for this task. Yet, the problem that these tools were designed to solve remain very prevalent, if not pervasive.
The reason that the problem remains and that Leo will not solve the problem either is relatively simple. Simply put, the problem is garbage-in, garbage-out (GIGO). These tools are not able to determine the purpose of the code or the intent of the programmer that is writing it. These tools cannot read the minds of the programmers. The tools rely on the programmer to write out their thoughts and the intended purpose of the code.
Most programmers are unwilling or incapable of performing this critical step thoroughly. All too often, they use shorthand and expect the reader to understand what they mean. Or, they believe that the reader should be able to understand their thought process by reading the code itself. Furthermore, they assume that if the reader can't do this, they are simply not a good programmer (1337).
To go a step further, many programmers are not capable of clearly expressing their thoughts in their native tongue. These people are quite brilliant and can do amazing things with their code but, they can't express their thoughts to another person unless that person is indeed, able to read and comprehend the code itself.
Now, in fairness to the programmers, we have to look at what they do and what they are taught. Most programming languages are all about efficiency. They rely heavily on abreviations and aliases, why do you think it's called code? They are designed to require a minimum or typing while providing a maximum of functionallity. The programmers themselves are always striving for increased efficiency both in their code and in the way they get the code done. They always try to put out more which leads to further shortcuts and abreviations. This all tends to make programmers minimalists and their documentation clearly reflects this.
So, Leo is unlikely to provide any documentation breakthroughs. The old rules still apply, garbage-in, garbage-out. The best idea I've seen was an earlier post, where the documentation is written first and then the code is developed to match the documentation. But, honestly, which of us going to do it that way. That's a lot of work and our ingrained habits are going to be hard to break.
This wouldn't be so bad if you actually was funny, Jack. But regrettably, you are not, and if someone laughs, it is you they are laughing off.
IOOC 911.11? Would that be the International Olive Oil Council, or the Iranian Offshore Oil Company?
Not to feed the troll, but for the benefit of any impressionable young programmers:
The goal of a programming language is to provide a machine with a set of instructions, not to sit down and read it a story.
Programming languages intended for use by humans (as opposed to languages intended primarily for machine generation) have multiple goals, three of which are to be human-writable, human-readable, and human-maintainable.
Literate programming may not be a perfect solution, but it's addressing a real issue. Current programming languages tend to be pretty horrible at expressing abstractions in a human readable way. The ideal programming language would be one that allowed you to express abstractions at the level of the problem domain, yet was able to translate that into something as efficiently executable, or close to it, as something written in a lower-level language. Literate programming allows you to do something along these lines, although it still involves a fair amount of "manual intervention" on the part of the programmer.
Its ugly, but it seems to help me out.
Need a Linux consultant in New Orleans?
I am more of a technical writer than a programmer (well, really, I'm not much of a programmer at all), but it was always clear to me that 90% of the software development headaches I lived with at various companies could have been resolved with minimal effort early in the project.. IF anyone cared about using a methodical approach to project documentation.
But nobody likes documentation. Writing it. Reading it. Just the word makes some people itch. For some reason, this is something that BOTH business managers and programmers don't get: documentation saves work. It is a way to produce a testable set of requirements, then a testable architecture/design, then a way to match up features and metrics in production and testing.
I mean, why does everybody think writing the manual is the LAST thing you do when you make software? With all the snarky "RTFM" comments I hear from geeks, I should start a new variant...
"PUHLEASE! BEFORE YOU START CODING, WTFM!"
I've got a bad attitude and karma to burn. Go ahead. Mod me down.
For a project I am working on, I needed to extend CWEB to do some things Knuth hadn't thought of, and I found that excessive cleverness in the data structures made it much more difficult to extend than it should have been, so that Knuth could demonstrate clever data structures that probably add a few percent to the performance over what he could have achieved with more prosaic ones (Knuth does not document why he made these excessively clever design choices, nor whether the performance advantages they offer were significant).
Similarly, a recent thread on comp.text.tex recently asking about the extensibility of TEX produced a number of comments from those who know about how unextensible and unreusable TEX really is.
So, while I use literate programming (CWEB) to document a lot of my own code, I don't believe in all these years, that I have ever seen a good example of literate-programming that looks towards the future (refactoring, extending, reusing) as opposed to generating a fossil with that comes with a good story of its life and times.
At least the idea is nice. Attempt to keep the doc in sync with the code.
;-)
I hope you meant "keep the code in sync with the doc".
in our environment most of the doc is actually in presentation forms, some diagrams, word documents, etc. These also need to be kept in synch with the code.
Ummm... You mean the code has to be kept in sync with these docs, right?! Please?
From what I've skimmed of Leo, it's certainly not designed to generate/update docs after you wrote code. Thank goodness. Having to update docs to match the code can be a serious symptom. There are exceptions, of course, but in my opinion, if you're updating your docs -after- your code has already changed so often that you need a -tool- for it, welll....
So you could say that Leo turns literate programmers into reference librarians ;-)
-Edward K. Ream
Old Qbasic had an interesting way of doing that. You just put the right symbol at the end of the variable. It forced you to follow the standard, because anything which wasn't declared otherwise was automatically a single precision floating point number(which hurts speed -- a lot.)
It's been a long time.
I've used both CWEB and noweb, the latter for a large scientific computing project involving (among other things) a large number of tensor operations. While I've thus found the TeX math typesetting features invaluable, literate programming has some serious drawbacks.
//! or /*! */ comment and then some TeX formatting in my source code and strip it out later to make my documentation.
...
/*! Einstein's equation
The most common problem for me has been the function/code chunk dichotomy. You might have a code chunk like "Set initial conditions" and only later realize that your chunk is too long and you need a function: set_initial_conditions(). Literate programming makes it so easy to write chunks of code without wrapping them in functions that your code ends up with too many chunks. If you do take the time to make functions then you vitiate much of the advantage of your literate programming chunks, since you end up just deleting the chunks and replacing them with descriptive function names.
Another serious problem is that it is very difficult to invert a literate program into human-readable source code; i.e., if you decide to junk CWEB and go back to C source and header files, you are in big trouble, since the machine-readable source code is horrendous -- not to mention stripped of all comments! So you really make a huge commitment if you decide to go the literate route.
Having used lit. prog. for several small projects and one big project I appreciate some of its advantages, but on balance I think that well-documented standard code is better. The only thing I really miss in standard coding is TeX math typesetting, but this is easy to rectify. I just wrote a simple program to convert a regular source file into LaTeX. I use a Qt-style
einstein.cpp
is $G^{\alpha\beta} = 8\pi T^{\alpha\beta}$.
*/
for (int i = 0; i != 4; ++i)
for (int j = 0; j != 4; ++j)
G[i][j] = 8*pi*T[i][j];
...
The commands
% simple_doc einstein.cpp > einstein.tex
% latex einstein
then produce a typeset version, with C++ code in typewriter font and the tensor equation in beautiful TeX math fonts.
Lit. prog. might be good for some large, mainly single-author projects such as TeX or Mathematica, but it adds a layer of considerable complexity to your code base, forcing everyone who uses it to learn your system. It will also never make good programmers out of bad ones, and in some ways actually encourages sloppy code by making it easy to write chunks of code without good modular design. As a result, after my current project I'll probably not use a literate programming system again.
-Michael
I tend to do this too, when I'm developing, but I use a less precise C++ish pseudo code. It's the best way for me to think about code that will have to be shoehorned and implemented in a particular language that's likely a good implementation fit.
You could've hired me.
There's an old saying (was on a "Murphy's Laws of Computing" poster I used to have): "make it easy for programmers to write in English, and you'll find that programmers can't write in English."
Others have pointed out the all-too-common case where the code gets edited but the comments don't. This is bad, but not as bad as another common case: the programmer tries to comment the code, but his/her grasp of English isn't up to the task. This may be because English is a second language, or simply because the person specializes in computer languages, not human ones. In any case, the result is frequently misleading or incomprehensible comments that either do no good, or worse than no good. And, of course, deadline pressures never help.
I think Literate programming is a wonderful idea, but I don't think it's a practical one in many (most?) real-world environments.
Apparently literate programming was not enough to allow the developers of evisa.com to avoid making yet another site that only works with IE 5.5+.
Unimpressive.
Minimal comments and a language that creats documentation for you is much better. With Eiffel your classes automatically have their public members documented, and with the design by contract model the interaction between classes is obvious.
There are 4 boxes to use in the defense of liberty: soap, ballot, jury, ammo. Use in that order. Starting now.
Imatix, the makers of the awsome open source webserver Xitami, has a similar product called 'Libero'. It allows you chart and build your code as you go.
http://www.imatix.com/html/libero/
You say things that offend me and I can deal with it. Can you?
I am not that old, and I seen several cases of someone cutting as pasting some similear code, comments and all, and then not updating the comments with the minor changes. When the comments references one register, and the code a different one, the comment is useless. Even though the code is similear, you can be sure that something is different, otherwise the two functions would be combined into a different one. But what logically is different between the two? What was missed?
When the orgional was written 25 years ago in assembly for a different CPU,(previous model, old code will still run) by a guy who is dead, you are in trouble. (I'm thinking of a real case here)
Great documentation also doesn't help when it covers the wrong thing. I read the documentation for one module I needed to make minor changes in and discoverd nothing about the code, instead I found the rough draft for a book: Advanced tricks with internal OOA process (Don't look on amazon, it never got further, and in any case is just enough specific to that companies old precess that it wouldn't apply elsewhere).
The problem with documentation is that good documentation rarely exists, not that it is hard to get at. Literate programing sounds good, and it would be if everyone wrote good documentation, but nobody could find it afterwards. Instead nobody writes good documentation, but at least it is in accessable places. (Generally company specific, but most companys do a fairly good job of keeping it)
The argument was made that good code is self-documenting. I'm saying that good code only documents its own current behavior.
What is completely lacking is any indication of what should happen, as soon as the use cases become more complicated.
The original poster was implying that the code was so perfect, that everyone should shut up and worship it as the end-all, be-all of self-documenting code. I found many, many flaws with the code. If you want to write the perfect version of it, that meets all of my demands, go for it.
But - every time I add NEW requirements, you'll have to massively modify the code. As the code becomes more and more complex, it will have more opportunities to gain bugs. All this while, though, the documentation might remain constant, if it's written clearly enough.
*shrug* You're welcome to your opinion, but I'd appreciate it if you wouldn't post as an Anonymous Coward, so I could have a real debate with you.
Education is the silver bullet.
In one respect, literate programs are a lot easier to maintain in the long term than illiterate programs because it's much easier to come back to them after a few months away.
Since Pascal didn't support modules and separate linking, TeX and WEB weren't designed with any sort of reusability in mind. I don't think that there's anything inherent about literate programming that causes inseparable blobs of code like TeX and METAFONT to be produced.
I generally program so that one document == one reusable library. The Monday Status page contains links to some of the literate libraries written for the Monday Project.
For a project I am working on, I needed to extend CWEB to do some things Knuth hadn't thought of, and I found that excessive cleverness in the data structures made it much more difficult to extend than it should have been, so that Knuth could demonstrate clever data structures that probably add a few percent to the performance over what he could have achieved with more prosaic ones
Generally, collection management API's should be "wrapped" such that you can change the implementation without changing or reducing change to the application code that uses collection management.
Whether there is a performance penalty to such wrapping is hard to say. Generally, there will be some performance penalty for the "indirection" needed for hiding implementation.
For many domains, making the software easier for programmers to maintain is more important than speed. Some programmers get obsessive over speed for no good reason, and make stupid (change-unfriendly) code as a result. They should be embedded systems programmers if they get off on that.
(BTW, you don't need OOP to wrap collection handlers.)
Table-ized A.I.
I would like to distinguish between the techniques of literate programming and the practice of literate programming (LP) as it has always been done before Leo (traditional LP). The key technique of LP is what might be called "functional pseudocode." For example, here is a fragment of code that can be written in Leo:
The line: << do something complicated >> is a section reference. It works pretty much like a macro call. In particular, the code in the defintion of << do something complicated >> has access to the done and result variables. This is almost the entire content of noweb, one form of literate programming. It turns out that this technique can be extremely useful, as simple as it seems. Leo creates one or more "derived" files from an outline automatically when the outline is written, and Leo can update the outline from changes made to derived files when Leo reads the outline.In contrast to the technique of literate programming, the practice of traditional LP has focused on the central role of comments, and lots of them. Here is where Leo radically parts company with the LP tradition.
One's view of the proper role of documentation in a project hardly matters to Leo. You are free to use comments as you always did, though you will probably find that LP as implemented in Leo helps you out in unexpected ways. I discuss at length and in great detail the relationship between traditional LP, comments and Leo here. In short, discussions about the role of comments in programming (literate or not) do not get to the heart of Leo.
In fact, Leo often reduces the need for comments. Indeed, it is good style to organize Leo outlines like a reference book. Well-designed Leo outlines act both like self-updating tables of contents and self-updating indices. This is in marked contrast to the "stream-of-consciousness" or "narrative" style typically employed in traditional literate programming.
In my view, the essence of Leo is this: Leo makes outline organization the most important part of a program or a project. Both code and documentation could be considered secondary. At every moment, the overall big picture of a function, class, module, file or project is always at hand. Moreover, Leo makes outlines structure a part of the computer language. For example, I often define a Python class as follows:
The @others directive acts as a reference to all the text in all the outline nodes which are descendents of the node containing this class declaration. Such nodes are copied to the output (derived) file in the order in which they appear in the outline. The reference << declarations of myClass >> ensures that those declarations precede the methods. There are several other ways that outline structure is important in Leo; I won't discuss them here.
Leo fully exploits the organizational power of outlines. A single outline typically organizes an entire project. Outlines can handle large amounts of data with ease. Moreover, it is possible to clone any part of an outline so that changes to one clone affect all other clones. This is feature makes it possible for a single outline to contain multiple views of a project. For example, when fixing a bug, I clone all nodes related to the bug and gather them in a new part of the outline, called a task node. This task node effectively becomes a view of the project that focuses exclusively on the bug. Any changes I make to code are propagated to all other clones.
Earlier I mentioned that a well designed Leo outline acts like self-updating tables of contents and self-updating indices. Tables of contents you get for free: an entire outline is the table of contents. Clones create self-updating indices. For example, each task node acts like the index entry for that particular task.
- Edward K. Ream
None of that is true for technical writing. It's a discipline onto itself. It's not just about good writing. (I've known computer scientists who'd written award-winning papers and articles, but couldn't write technical docs worth beans.) It's about understanding your audience and the (often painfully boring) task of writing in the clearest possible language.
Not every project needs technical writers. If you're a small software shop, and you're building a set of components with an uncomplicated API, and hiring a professional writer isn't cost effective -- then yeah, use Javadoc or some other LP tools.
But for big projects... Back in 1998, I was in charge of production for the doc set of a large Java framework. Having the API docs embedded in the source code was a nightmare. Javadoc was supposed to allow any of the engineers who wanted to to do their own API docs -- but many botched it, because they didn't understand Javadoc or HTML very well. We had professional writers, but many of them couldn't be trusted with source code. Hell, some of them didn't understand why they couldn't edit the SCCS archives!
Worst of all was when the release cycle entered code freeze. Document freeze is always later than code freeze -- but you cannot let people modify the release code base during code freeze. The only solution was to split the source, then merge the docs back in after release. Very painful.
still haunts us poor programmers. Backwards compatibility is hard to sacrifice.
Do you believe in life after death?
This is absolutely on the mark.
I believe that WEB was a great improvement over Pascal at the time that Knuth began to use it. However, it does not solve the underlying software engineering problem. Knuth's style at the time of TeX, etc., involved very little abstraction.
The biggest problem this causes is that the major data structures in TeX do not have well-defined or factored interfaces that allow them to be easily changed or extended. Furthermore, important details of these data structures are basically undocumented, and often cause interdependencies between different portions of a WEB that are not at all obvious.
If you wish to see the problem face-to-face, look through TeX: The Program at the "inner loop" and see how many different sections of the WEB that you would have to understand.
A similar problem is his use of enumerations with certain magic values, where the magic is documented (or becomes apparent, while still undocumented) some distance away from the point of definition.
Another serious problem with WEB is that it allows one to completely obscure the sequential nature of the program. Many times, one chunk depends on initialization that was performed by another chunk. If Knuth decided to make some laconic comment rather than remind you of that initialization, good luck reconstructing the sequential dependencies.
If one is writing monolithic programs, writing them like a Russian novel might be easier to comprehend than one large unformatted source file. However, if one has the alternative of writing a highly modular program with clean interfaces, I don't really see any advantage to breaking up and rearranging the underlying code.
Maybe the reason Literate Programming never took off is because it wastes the time of good developers. I rarely have trouble reading code written by myself or the other developers at my work, and I can even completely rewrite someone else's software and get it almost all right.
I guess it would be useful for novice programmers who do not know how to write useful comments (that is, 'self-documenting' code, as well as actual comments).
If I spent the time writing document outlines and program plans and crap beforehand it would be just that, spending time for no reason; not to mention the design changes that often go on as you are actually writing code ; the last thing in the world I want would be to have to go back and change all these plans because I decided to change an aspect of what I was doing.
You're ignoring the really important parts:
/know/ that with any exported function, it will be given bad input. Even without bad input, I/O failures et al happen. Document what happens.
- Preconditions.
- Failure modes -- because you
- The semantics of each input parameter. Yay, it's really bloody useful to say "blah" is a C-style string. The semantics of it should be in a well-documented API -- in fact, somebody else using your code shouldn't even have to look at its internals.
- The semantics of each output value.
- Postconditions.
- When the function is useful and why.
- What drawbacks might make the function less useful.
- Sample calling syntax, including code that shows how the input was obtained.
Only the dead have seen the end of war.
I suppose the reason why Literate Programming has not caught on is simply that no major programming language forces you to do it.
Given the right tools within a programming language---say, a documentation tool such as JavaDoc, and some code and commenting conventions---and proper understanding of some software engineering methods concerning the thoughtful design of your software, it is quite possible to achieve what Literate Programming tries to achieve.
But Java, for example, doesn't require you to build a proper UML model, follow the code conventions, and JavaDoc everything in a way understandable for others. But nobody stops you from using those methods right now. The problem is just that doing Literate Programming---or, for that matter, any kind of proper, thorough documentation---eats up a lot of time, since easily around 50 percent or more of the total time spent on a project are concerned with documentation. And for most programmers, including me, it requires quite some effort to be disciplined enough to do such "proper" software development thoroughly.
In other words, it might be helpful to use a Literate Programming tool that forces you to document your stuff, but it is still up to you to create a proper design and documentation for your software.
I'm not a big fan of abusing Java's interfaces (an interface for each implementation hierarchy), but in a big project that has to be properly documented and strictly specified, this would seem to help.
The interface is after all closer to the specification level, so your documentation can be strictly about the specification. Then you can let the programmers code, document and freeze the implementation independently from the interfaces.
Since an interface doesn't have any implementation sourcecode, writers could be trusted with the files, and since the interface API per se is frozen at design, they can keep modifying the Javadocs without affecting the coders.
If the writers have to modify the API per se and recompile an interface, they are changing the specification (re-design) and of course the coders are forced to adapt their code to those changes.
But otherwise there would be no need to "split the source" and then "merge". All you would have to do is provide the Javadocs for your interfaces (plus a manual based on this, perhaps) and the Javadocs for your implementation (if implementation details are to be exposed, such as efficiency guarantees, etc).
If anything, I would think the split would improve documentation.
Freedom is the freedom to say 2+2=4, everything else follows...
I may be a bit confused here:
.NET?
What exactly is it that you cannot do with your source code in Visual Studio
I don't mean that the wisdom of MS has allowed them to put all functionality ever needed in Visual Studio.
I mean that every time I checked my source code was still there in a flat file, and I could modify it with a text editor, a perl script, or whatever I wanted.
I haven't seen any repository system from which I have to import/export source code or anything like that. Am I missing something?
Freedom is the freedom to say 2+2=4, everything else follows...
Of course it should. Anywhere that the code does not "document" the program, the progammer needs to provide explicit documentation or write clearer code. That's very very simple if you just consider that the code *is* the program. What documentation could be more correct than the code if you want to know what the program does.
Very nice idea, but I've never seen this work in practice. The problem is basically this: You just introduced an entirely different vector under which bugs can occur. These new bugs do not break the program in any visible manner, they just destroy the productivity of a maintenence programmer.
Example... Client decides to change the behavior of a component of a system after the program has been released. Programmer goes in and changes the code, but never changes the documentation. While making the change, the programmer notices that another requested change will cause the first piece of code to break in a very subtle way if it had not been changed.
6 months later, another programmer makes some changes and notices that a line of code is clearly not doing what the documentation says it should be doing. Feeling almighty and powerful, he modifies the line so it fits the documentation, thus overwritting the change from 6 months ago and introducing a subtle bug.
What happened? If documentation is not kept up to date (one more bug vector to worry about), the maintenence programmer will either lose time verifying which is correct or will "fix" a bug that shouldn't be fixed. Neither case is a good thing. Documentation bugs are especially bad because they are so transparent.
So which is worse? I would warrant that the second is far worse. Any documentation that can be embeded directly into the statements of the language through variable names, function names, language constructs, data structures, etc are a great benefit as they cut down on the number of instances where doc bugs can occur.
Nonetheless, it's is definitely necessary to document particulary nasty chunks of code, but keep the documentation at the highest level possible. If it is a system overview comment, it belongs in a design doc. If it describes how a black box *should* work, it belongs at the highest level of that box (ie, class or function). If it is a single line genius piece of code, by all means, document it. But be assured that anyone who changes it will probably have a tough time understanding it, will have to read the documentation, and will likely remember to update the documentation out of appreciation if nothing else.
If this is tough to accept, look at one of your own statements..
But - every time I add NEW requirements, you'll have to massively modify the code. As the code becomes more and more complex, it will have more opportunities to gain bugs.
Really? And so as it becomes more complex, it will likely need documentation to describe the additions that are being glued to the side of the original design, right? Oh, right. Maybe it will remain constant?
All this while, though, the documentation might remain constant, if it's written clearly enough.
Yes, it might. Are you going to remember to check it, especially if it is right *most* of the time...
So, there you go
In addition IE is required for the pages that have speech, since that uses MS Agent, and there is no comparable technology for Netscape.
You used MS-Agent and technology in the same sentence! I can think of a portable systems which provide text-to-speech (festival), and its certainly possibly to provide the page without "speech", or with a few sound clips in ogg or mp3.
Also, some languages are trivial to text to speech, such as japanese. (trivial as in a perl script and a directory with sound clips could probably doit in real time)
Well, mostly my problem is that I have no way of getting any version of IE going, and I really wanted to try the language sections, so I am bummed
Your example actually is about a different area of poor coding skills, though it does relate to commenting. Obviously, the poorer the code the more comments that are needed to understand it. For example: If I was non-english speaking and had to take a translator with me to make myself understood. If my command of english is bad, my translator will have to jump in more often and say "he means
As far as your rant, the problem is real enough, companies do sell some crappy software I won't deny that. But your implied solution is completely wrong. The idea that "companies should not be allowed" to sell anything no matter what the quality is just nonsense. Nobody has the right to dictate to anyone else what they can or cannot attempt to sell. The fault doesn't lie with the companies selling the software it lies with the consumer who continues to purchase it. It's completely about demand. Consumers have given their approval of companies selling buggy software by their willingness to buy it. The reason that you are on the hook for bugs you weren't responsible for is your fault (or someone higher up who bought the software for your company), not the developer of the software. If you knowingly buy software that a company has attached a 'no warranty' EULA to the responsibility is yours plain and simple. Claiming that they should be illegal is one step away from banishing the GPL.
Software that could potentially put lives in danger should be thouroughly examined by the people responsible for buying it. Should the government only buy software that is warrantied by the developer, sure. We have to put our faith in the government for our safety. Does this mean it should be illegal for any company to put out no warranty software, hell no.
When it comes to EULA's I don't feel they should be legally binding when they are legally binding before someone has the chance to read and accept them (sorry UCITA you're a crock of shit), or at least if after purchasing software and reading the EULA the place where you bought the software is legally required to accept a return in you don't agree to the license. It shouldn't be a long drawn out process to contact the manufacturer and have them refund your money.
As a side note, there or dozens of other problems with EULA's not directly related to this discussion that I have problems with, possibly the most serious being the belief of corporations that they can nullify your rights through them.
I'm the big fish in the big pond bitch.
The reason geeks don't like writing too much documentation is simple. It's not laziness (well not always), it's just tedium with human language (or poor speeling and grammer to).
Project completion includes documentation.
Professionalism demands it.
Always.
Full steam ahead.
The worst cause of feature creep and software bloat is delineated in your rationalization. The "simple" change should be to your documentation, and then the code should be updated to reflect that change. Note that that change in the spec is usually considered a valid reason for an increase in the revision number.
The worst thing in the world for a software company (profit motivated) is a moving feature set, and never reaching 1.0.
Of course the documentation will change. I forgot to mention how important docs are in the process of "change management". It's like war: no battle plan survives the first engagement with the enemy, but that is no reason not to have one. As long as you change the docs to reflect the new features/behaviour, there is no problem with docs "getting out of date" with respect to the code.
Besides, if you are writing the docs and someone notices a glaring issue, you can resolve it before telling someone to start coding. The earlier, the better. And you WILL do the same changes later in the project anyhow, with a few hundred percent increase in the workload.
This is why (most) programmers make horrible tech writers: they are too involved in the code to be concerned about issues that affect usability and project management.
I've got a bad attitude and karma to burn. Go ahead. Mod me down.
If you REALLY need to do something that the IDE isn't capable of then you can write your own tools. VAJ provides a Java API for this and it is really easy to use. You can then make the IDE do anything that you want, as long as you are able to code that behavior in Java. You can also you vi and Emacs to edit your code in VAJ if you really want to.
Lasers Controlled Games!