Olá Habr!
Com que frequência você ou seus colegas não conseguiram descrever seu próprio código com algumas frases?
Trago a sua atenção uma tradução do artigo "Como escrever código de fácil descrição", de Cedd Burge , no qual ele compartilha seus conselhos sobre como evitar tais situações.
Quando o código é difícil de descrever com palavras, a maioria das pessoas precisa usar a imaginação para fazer isso. Por esse motivo, a energia mental é desperdiçada e o risco de erros na interpretação do código aumenta. Pessoas diferentes ainda perceberão as palavras à sua maneira, o que causará confusão ao discutir o código.
Como regra, essas discussões se tornam um terreno fértil para erros que surgem devido a mal-entendidos, e a correção desses erros geralmente leva ao aparecimento de novos erros pelas mesmas razões. No final, obtemos um código incompreensível com o qual ninguém deseja trabalhar.
Exemplo de código indescritível
Você pode pensar que o código é apenas uma linguagem escrita. Se o código parecer simples, ele poderá ser facilmente lido, descrito e entendido. No entanto, esse nem sempre é o caso.
A decisão geral abaixo determina se um ano é bissexto.
(divisibleBy(4) and not divisibleBy(100)) or divisibleBy(400)
Este é um código simples. Ele chama funções 3 vezes, possui 3 operadores (e, ou, não) e dois níveis de aninhamento.
Mas acho que se você tiver um segundo para descrever esse algoritmo usando palavras, terá dificuldade.
Talvez “um ano é um ano bissexto se for divisível por 4 e não divisível por 100 ou divisível por 400”?
O problema é que, em palavras, diferentemente do código, não há colchetes. Portanto, é difícil descrever adequadamente a condição em palavras e se a palavra "é divisível por 400" se refere a "divisível por 4" ou "não divisível por 400". Para contornar esse problema, você pode especificar colchetes com a mão ou fazer pausas mais longas entre as condições, mas a probabilidade de um erro ainda permanecerá grande.
Refatorando o código descrito
Podemos primeiro descrever as condições em palavras e só depois reduzi-las, tornando-as o mais claras e concisas possível. Vamos começar assim:
"400 anos é um caso único. Se um ano é divisível por 400, então este é um ano bissexto. 100 anos também é um caso único. Se um ano é divisível por 100, então não é um ano bissexto, a menos que seja divisível por 400, então a prioridade para o caso especial é "400 anos". Se não houver casos especiais, este ano será um ano bissexto, desde que dividido por 4 ".
Parece claro, mas não conciso, então encurtaremos um pouco o texto:
“Se o ano é dividido por 400, então é um ano bissexto. Se é dividido por 100, então este é um ano normal, mas quando dividido por 4, é um ano bissexto. "
Se transformarmos essas palavras em código, obteremos algo como o seguinte:
if divisbleBy(400): return LeapYear elif divisbleBy(100) return NormalYear elif divisbleBy(4): return LeapYear else: return NormalYear
Conclusões
Difícil entender o código é comum para quase todos os programadores. Ajudaremos a nós mesmos e a nossos colegas se escrevermos um código que seja facilmente descrito em palavras.
E o mais importante, escrever código dessa maneira é mais fácil, pois não há esforço mental vã. O "truque" é que o algoritmo é primeiro descrito pelas palavras que serão usadas mais tarde para escrever o código.
Em muitas organizações, o código já começou a ser descrito em palavras em testes de aceitação ou histórias de usuários, o que pode melhorar a produtividade.