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?
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.
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.
+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
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.)
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.
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.
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.
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
The main idea of literate programing is to write programs as mathematical texts. One can define what does it mean every concept needed in the program as clear as possible, then explain how it is implemented in the language and why one decided to do it in such way and not other or what is going to be changed later.
The changes can be also documented by commenting the piece of code to change and inserting the new one explaining the reason for the change. Some changes may depend on transformations of the code to optimize it's performance. For example making one loop, instead of 2 loops in some C like language, change one expression for a simpler one, etc. Or something more complex like changing other data structure to represent information. Every change is well justified and documented. One can understand about the problem domain of the program, just reading the source code, understanding it in depth. Avoiding mistakes due to ambiguities. The genesis of the program is completely documented, one can recall everything later, because every thought is in the program.
Strictly speaking one can write literate programs with plain text, if the program is developed, but typesetting it in TeX/LaTeX is the most aesthetic, functional and easiest way, because it is not difficult to place LaTeX markup within the most programming languages.
It is natural to write literate programs in Haskell, because a Haskell script contain a set of declarations not instructions. You can place all declarations in any order. That is different in other languages where it is important to order the instructions in a particular way.
I have not used web nor cweb or similar programs, but those programs help to typeset the programs in a logical order for a human, whereas the program modules can be generated for proper compilation.
There is a LaTeX package called listings which is easy to use you can start every piece of code closing the comment and ending the code opening a new comment, as far as I remember, something like this:
% /* begin of literate program
\documentstyle{article}
\usepackage{listings}
\lstdefinitions here I do not remember the syntax. Here one can define
a replacement for startcode*/ and /*endcode for spaces.
more definitions here
\begin{document}
Your explanation including formulas like $s=c\times\sum_{i=0}^{i=N} x_i$ etc.
\begin{lstlising}
startcode*/
s=0
for(i=0;i<=N;i++) s=s+x[i];
s=c*s;
etc..
/*endofcode
\end{lstlisting}
More explanation ...
\end{document}
% end of literate program */
in the preamble of the text you can define startcode*/ and /*endofcode as keywords to replace by spaces in the extra definitions for the listings package. See the package documentation.
at the end of the LaTeX source simply type:
% end of literate program */
which is a comment in LaTeX in the beginning you can place the opposite:
% /* start of program
Removing the % LaTeX comment sign when you want to compile the program, and putting it again when compiling by LaTeX.
If you have never used LaTeX before, you can start with plain text first. Maybe combining it with doxigen to index everything. Doxigen is not needed with LaTeX because it is a typesetting system, where you can create several indexes, hyper-links, structure the documentation as a book.
Haskell programs are usually written in literate style. Maybe it is a good idea to browse some book or article to see one.
来源：https://stackoverflow.com/questions/219168/literate-programming