Código que fala por si só

Uma justificativa (ou desculpa, dependendo de que lado se olhe) bastante comum de equipes que desenham diagramas para qualquer pequeno aspecto de suas aplicações é que eles servem para ajudar a ler o código. Tornam aquela bagunça emaranhada que é o código em algo mais dócil. Traduzem a verborragia computacional em algo mais compreensível para um mero humano.

O objetivo aqui é certamente louvável. Quem não quer uma aplicação fácil de entender? O problema é que este tipo de discurso parte de uma premissa bastante questionável: a de que código é inerentemente difícil de se ler e entender. Estou usando aqui o exemplo dos diagramas, mas o mesmo problema acontece quando se tenta escrever comentários para cada linha de código. Muda o paciente, mas a doença é a mesma.

Digamos que você esteja escrevendo um livro. Você pensou em um bom tema para a estória, delineou vários personagens e conseguiu imaginar até um cenário interessante para o pano de fundo. Mas seus dotes literários não estão muito apurados e o texto começa a ficar meio emaranhado. Você não sabe onde terminar uma cena e começar outra, não sabe onde encaixar os diálogos e qualquer um que começa a ler se perde depois do quarto parágrafo. Apesar disso você tem uma boa estória para contar. O que você faz? Enche o livro de figuras coloridas? Faz um filme para ser distribuído em conjunto?

Claro que não. Você reestrutura a história e reescreve o livro se for preciso. Você não faz uma representação paralela dele em outra mídia, você torna a mídia original mais acessível. Se você não conseguir fazer isso, é melhor procurar outra coisa para fazer. Talvez você possa aprender a escrever melhor se estudar um bocado. Ou talvez você não tenha talento mesmo.

Para o código a solução é a mesma. O texto do programa deve falar por si só, não se deve assumir que há alguma outra representação alternativa para torná-lo mais claro. Se o relacionamento entre as várias partes do código está obscuro, ele deve ser reestruturado de forma a ficar mais claro. Se o nível de detalhamento das rotinas chamadas dentro de um trecho está muito perto do metal bruto, agrupe alguns blocos em rotinas separadas ou crie novo objetos. Faça o que fizer sentido, mas não deixe o código ficar sujo. Assim como todo bom escritor pensa o tempo todo em seus leitores, pense o tempo todo em quem vai ler seu código.

Isso não quer dizer que nunca devamos usar uma representação gráfica ou comentários para explicar código. Voltando à analogia dos livros, ilustrações são coisas legais de se encontrar, só não devem ser partes essenciais do conteúdo. Talvez fique mais fácil entender o que o autor imaginou com elas, mas qualquer bom livro que tenha as ilustrações removidas continuará tão bom quanto antes.

3 thoughts on “Código que fala por si só

  1. Concordo e considero a documentação como uma manchete de uma notícia que o código irá contar.

    Em jornais, somos atraídos por aquilo que realmente nos interessa através de uma manchete, nos evitando varredura completa página a página, no entanto, identificada a página, se o texto redigido não for lá estas coisas, perdemos o interesse rapidamente e iniciamos a busca por notícias mais interessantes.

    Trazendo para o ambiente de desenvolvimento, nem sempre é possível descartar um código para colocar outro em seu lugar, e como dito pelo Thiago “todo bom escritor pensa o tempo todo em seus leitores, pense o tempo todo em quem vai ler seu código”.

  2. Como diria Uncle Bob:
    “Professionals write clear and clean code.”

    Quando você encontra código com muitos comentários tentando explanar o que está ocorrendo então há grandes possibilidades de ali haver um “bad smell”.

    Excelente post, parabéns.

  3. Concordo. O código deve ser claro e simples. É possível compreender código alheio quando está bem estruturado. Depois de estudar por algumas horas, normalmente consigo ter uma idéia do todo. Comentários ajudam, mas nomes de variáveis, métodos e classes bem escolhidos fazem toda a diferença. Há exceções à regra, claro, mas normalmente são algoritmos intrisicamente complicados, nos quais poucos desenvolvedores/pesquisadores trabalham.

Comments are closed.