Literate programming

views:

645

answers:

+7 Q:

Literate programming

Literate programming is a way of developing software where documentation comes first, then the coding. One writes the documentation of a code snippet, and then writes the implementation of the snippet. The visual appearance of the software source code would be a plain document like word, with code paragraphs in it.

I am trying to convert the dev shop I work to use only literate programming, as it brings great advantages to code readability and maintenance. However, due to the lack of tools the LP usage is limited in the company. For example, the ideal way to program literate is to write a paragraph using word markup, and then insert a subparagraph with the implementation. But i cannot seem to find any good tools for VS200x to perform LP with.

Ideally, such a tool would look just like Word 2007, but integrated into the IDE. When the coder sets the cursor on a code paragraph, it would have all the functionality provided just like we have now in our IDE.

What are good tools for LP, with .NET and VS200x in particular?

+2 A:

I can only suggest you markup your code with doxygen comments, then you can generate the documentation from your code, which I know is almost a backwards ways of doing what you want, but at least you end up with the desired result: code and documentation that comes from the same source files. Obviously this has the advantage that you use your existing IDE for coding that comes with all the usual code-friendly goodies.

If you're trying to convert your dev team, this approach might be easier for them to swallow than a full-blown literate methodology, they're still happy with the coding being the same, but they have to write better documentation embedded in the code.

That's the best I can suggest, see what your team thinks of the idea.

gbjbaanb 2008-10-20 17:27:03

Doxygen is fantastic at giving you insight into complex, inter-dependent code.

endian 2008-10-20 18:36:42

+2 A:

The only non-esoteric language I know of which actually has support for LP is Haskell, and to be honest, I haven't heard much demand for LP in modern programming languages. Most people seem to be satisified with using inline documentation formats (javadoc, rdoc, etc.)

JesperE 2008-10-20 17:30:20

Most people aren't very bright programmers.

omouse 2009-11-05 07:45:27

Correction: most programmers aren't very bright programmers. :-)

JesperE 2009-11-05 09:13:38

+1 A:

My apologies. I should have mentioned that we are already using Doxygen with an automated doc build script. We use the .NET doc tags where possible, and where the .NET XML doc tags come short we mix in doxygen tags. This works quite well. The point is that production decreases quite much when writing documentation: We (humans) are very bad in producing documentation without any WYSIWYG editor. Not to mention error sensitive.

The team is currently in the phase to convert the mindset from coding straight ahead to first writing documentation, then code. This is the most important step, as it lets the coders embrace the LP paradigm.

There is a market here for a VS plugin that does it, i guess.

Also, Doxygen indeed seems to be a nice tool for actively using the LP method solution to this problem. Though it is very limited in use.

2008-10-20 17:32:13

+9 A:

Kudos to you for trying to improve the way your team works. As long as you're trying to do that, you have an advantage over those that do not.

I used Literate Programming for a project once. It was really hard, and the results were really good. Seemed like a reasonable tradeoff.

However, today I'd rather take a different approach: instead of prose for humans and code for machines, I'd rather write code that is so clear that humans don't mind reading it. When I feel the urge to write a comment, I think "I could make this code clearer". That means I'm writing less documentation, not more.

Well, good luck with whatever path you choose.

Jay Bazuzi 2008-10-20 17:35:16

I find that one practical and dirty way to do it is to extract stuffs to a separate function. If you want to write `// First, get user input`, replace the whole thing with `GetUserInput()`. If you want to write `// This how it works...` inside a function body, extract it to `MagicalMathFormula()` with a per-function comment block for explanation (which gets extracted nicely with doxygen)

kizzx2 2010-08-21 04:31:27

Yes, most statement- and expression-level comments can be transformed in to function names, with Extract Method. Now you have too many functions! Find data and functions that are related, and Extract Class. Pretty soon you'll be doing OOP!

Jay Bazuzi 2010-08-21 16:22:30

However, today I'd rather take a different approach: instead of prose for humans and code for machines, I'd rather write code that is so clear that humans don't mind reading it. When I feel the urge to write a comment, I think "I could make this code clearer". That means I'm writing less documentation, not more.

Thats what we do also. Though for a lot of code we produce, writing clear, human readable code just isn't enough. What if you want to explain an image rendering function? Better explain it using an image, instead of writing half a page describing it.

2008-10-20 17:40:39

You should write a technical paper with images and TeX formulas explaining how it works, then put a pointer in the comments to it. -- Most of the time the pointer may not be even needed, if your function is correctly named e.g. `PeterJohnMaryTransform()` then you just need a doc page named that and the user would look it up himself.

kizzx2 2010-08-21 04:43:02

+2 A:

+1 for trying to improve your team's process

-1 for going down a dead-end path

with all due respect to Knuth, unit tests are better than documentation

unit tests cannot become out of date
polluting the code with prose is a huge distraction when debugging
if your code really requires that much exposition, it is probably poorly designed and buggy

Steven A. Lowe 2008-10-20 18:23:28

Heh. As for "unit tests cannot become out of date", I've just spent all morning trying to get my old unit tests to link against a contract work project that someone else modified without checking against my tests.

Sol 2008-10-20 19:23:00

@[colomon.livejournal.com]: double heh - if you had documentation instead of unit tests, you could just ignore it...and then later you'd REALLY be screwed ;-)

Steven A. Lowe 2008-10-20 19:55:48

Seems like an awful lot of discipline is needed.. first of all to do LP. and then to maintain LP snippets with every change to code..

Gishu 2008-10-21 05:52:57

-1 for your three wrong bullets: unit tests actually can become out of date; prose helps you understand what's going on, even in a debugging session; exposing the ideas behind some code to humans (not to be confused with code scoping) does tend to make design better.

ngn 2008-11-05 06:15:35

@[ngn.myopenid.com]: thank you for explaining your downvote; this is how people learn. I would expect that unit tests that are out of date would FAIL and thus draw attention to themselves... The rest of your points may to some degree depend on the writer and reader; this looks like overkill to me

Steven A. Lowe 2008-11-05 17:24:21

Exactly, those which get out of date fail. Btw, you correctly mentioned the link between docs and unit testing (oh, I just love Python's ``doctest'' module).The rest: that's what literate programming is about. Honestly, I sometimes only read the comments when I inherit a codebase. Docs matter.

ngn 2008-11-05 18:22:07

@[ngn.myopenid.com]: docs are immensely useful when they are correct. This is unfortunately rare in a living system. I prefer working Unit tests to doc any day. Sadly, most systems have neither!

Steven A. Lowe 2008-11-18 15:59:38

+! because you are right; also, good link from the other LP question.

Chris Lively 2008-11-18 16:08:36

-1 LP might not be viable, but [unit tests aren't always good](http://stackoverflow.com/questions/856115), and [documentation is often useful](http://stackoverflow.com/questions/400382/how-does-a-good-developer-keep-from-creating-code-with-a-high-bus-hit-factor/400436#400436).

ChrisW 2010-09-08 23:09:51

@ChrisW LOL - links to your own questions and answers don't negate the arguments, though they do add to the discussion. Thanks for sharing!

Steven A. Lowe 2010-09-09 16:05:25

+1 A:

I'm not aware of any modern tooling for Literate Programming. I have done some WEB programming 15 years ago.

Doxygen is a nice tool, but doesn't help at all with LP. The problem is that LP focuses on writing code for humans to read. There is no good support for successive refinement/disclosure. LP needs a view on the source code that has a different structure than the file-class-attribute/method in VS. NSpec might be somewhat better, but also is too much bottom-up.

Stephan Eggermont 2008-11-18 16:20:29

+1 A:

Here is a tool that was developed with Literate Programming in mind: http://webpages.charter.net/edreamleo/front.html

I never did LP myself so I cannot comment on how good leo is with it...

I did use leo as a single user, but didn't succeed having a colleague use it too on shared code.

2008-11-18 17:13:58

Hello source novel authors,

As some one referred to DOxygen here : although this does not allow real Literate Programming (as an example of limitations, this does not allow to have a reordered view on sources), it however seems to be recognized as a valuable tools in this area, by its own advocates (LP advocates) : it is mentioned right at the top of this reference page about LP tools : Literate Programming Tools

Hibou57 2010-02-24 07:34:36

ansaurus

tags:

views:

answers:

Literate programming

related questions