Literate Commenting

Literate programming is a programming methodology that combines a programming language with a documentation language, making programs more robust, more portable, and more easily maintained than programs written only in a high-level language.
Donald E. Knuth

Literate Programming é uma idéia genial. Se você é programador e gosta da arte de programar, sugiro que leia o livro ou que vá direto à fonte.

Por volta de 1995, quando eu estava lendo o livro, tive muita vontade de experimentar a metodologia. Mais ou menos na mesma época eu estava ouvindo o disco Aqualung do Jethro Tull. Na capa do disco havia um texto, meio que um poema, que me interessou--talvez porque eu não tenha conseguido entendê-lo. Algumas palavras do texto chamaram a minha atenção, não por sua relação com o texto em si, mas por sua relação com o meu trabalho como programador. Daí me veio a idéia de tentar usar o texto como comentários de um programa. O programa não precisaria fazer muito sentido, mas precisaria ser compilável e "casar" o mais perfeitamente possível com os comentários.

Até que o exercício não foi muito difícil. Depois da primeira versão, corrigi alguns poucos bugs e, modéstia às favas, fiquei bastante satisfeito com o resultado. Cheguei até a pensar em mandá-lo para o Knuth como sugestão para ele usá-lo como exemplo em algum novo livro seu, mas desisti. Possivelmente ele diria que isto está mais para Literate Commenting que para Literate Programming.

De qualquer modo, eis o resultado do meu esforço. Ah! Estou aberto para receber críticas e sugestões. As modificações incorporadas em futuras versões do programa terão suas fontes devidamente citadas. :-)

#include <cassert>

typedef int (*Entity)();

int Man()
{
// 1. In the beginning Man created God;
// and in the image of Man
// created he him.

    Entity God = Man;

// 2. And Man gave unto God a multitude of
// names, that he might be Lord of all
// the earth when it was suited to Man

    Entity &Lord = God;
    Entity &Jeovah = God;
    Entity &Alah = God;
    Entity &Rah = God;

    static bool suited = true;

    if (suited)
        suited = false;
    else
        return 0;

// 3. And on the seven millionth
// day Man rested and did lean
// heavily on his God and saw that
// it was good.

    for (unsigned day=0; day != 7000000; ++day);

    assert(God != 0);

// 4. And Man formed Aqualung of
// the dust of the ground, and a
// host of others likened unto his kind.

    char *Aqualung = new char[1024];

    char *host[10];

    for (int i=0; i < 10; ++i)
        host[i] = new char[1024];

// 5. And these lesser men were cast into the
// void; And some were burned, and some were
// put apart from their kind.

    void *lesser[10];

    for (int i=0; i < 10; ++i) {
        if ((i % 2) == 0)
            delete[] host[i];
        else
            lesser[i] = static_cast(host[i]);
    }

// 6. And Man became the God that he had
// created and with his miracles did
// rule over all the earth.

    God();

// 7. But as all these things
// came to pass, the Spirit that did
// cause man to create his God
// lived on within all men: even
// within Aqualung.

    char *Spirit = "main";

    Aqualung = "main";

// 8. And man saw it not.

    bool saw = false;

// 9. But for Christ's sake he'd
// better start looking.

    assert(saw);
}

main()
{
    Man();
}