[Linuxcall] Literate Programming

[Nelson C. de T. F. <nf...@in...>]

> > > Seria algo como inserir a documentação em forma de comentários no
> > > meio do código? Se for isso, legal, acho que isso quebra um galhão.
> > 
> > Eh isso e muito mais. A ideia eh que voce organize o programa como se
> > estivesse escrevendo um artigo, misturando texto e codigo, de modo que
> > voce nao precisa ordenar o programa segundo a logica do computador.
> 
> Interessante mesmo... 
> Eu ainda não li os links que vc passou prá aprender mais sobre isso e
> poder opinar, mas, parece interessante. Apesar de que eu _no momento_
> apóie a idéia do CVS antigão... 

Na verdade, Literate Programming não está diretamente relacionada com o
uso ou não de CVS; aliás, seria ótimo usar os dois simultaneamente!

Aqui vão alguns trechos de um artigo de Mark Jason Dominus, que explica
porque o método de documentação de Perl, chamado POD, não é Literate
Programming:

---

The first idea is that good program documentation shouldn't be squeezed
into little `comments'. It should be structured more like a technical
article for a journal, and it should have all the support that a journal
article usually gets, including good typesetting. The programmer should
have the opportunity to annotate each section of the code with as much
explanation as is necessary and appropriate.

So far this sounds just like POD. Where POD comes up short is in the
other important idea.

Knuth's other idea was that the best order to explain the parts of the
program in a journal article is not going to be the same as the order that
the computer needs to see the code. When you write a computer program, you
have to present the code to the computer in a certain order, or else it
doesn't work. This order might not be a good order for explaining the way
the program works.

For example, you might have

unless (open(F, "< $file")) {
           # 55 lines of error handling here ...        
        }

$line = <F>;

When you're explaining the program to someone else, you want to talk about
opening the file and reading a line. You don't want to have to interrupt
yourself with a huge digression about the error handling just because the
computer language you're using requires that you put the error handling in
between the open and the read; you'd might prefer to talk about the main
logic first, and return to discuss the error-handling part much later.

For the same reason, having the error handling code in the middle there is
no just an impediment to you when you try to explain the code, it's also
an impediment to another programmer trying to understand the code. One
frequent criticism of C is that it's too hard to follow the flow of logic
because it is visually dominated by block after block of error handling
code.

---

Para maiores detalhes, leiam o artigo!

"POD is Not Literate Programming"
http://www.perl.com/pub/tchrist/litprog.html

[]s

Nelson

__________________________________________________________________
Nelson Ferraz                           Insite - Solucoes Internet
e-mail: nf...@in...           http://www.insite.com.br/