Clareza no código

Ontem no trabalho tivemos uma discussão sobre um trecho de código complexo, onde faltava certa clareza para que se pudesse entender a real engenhosidade do algoritmo empregado.

Foi então que meu colega Antônio surgiu com sua sabedoria incentivadora, nos trazendo o seguinte exemplo de como clarificar uma instrução mal explicada:

“The Landing Pilot is the Non-Handling Pilot until the “decision altitude” call, when the Handling Non-Landing Pilot hands the handling to the Non-Handling Landing Pilot, unless the latter calls “go-around”, in which case the Handling Non-Landing Pilot, continues Handling and the Non-Handling Landing Pilot continues non-handling until the next call of “land” or “go-around”, as appropriate.

In view of the recent confusion over these rules, it was deemed necessary to restate them clearly.”

– British Airways memorandum, quoted in Pilot Magazine, December 1996

O texto acima foi publicado pela British Airways em um memorando visando clarificar instruções previamente divulgadas que haviam gerado certa confusão entre os leitores. Será que o texto clarificou?

Quanto ao mundo dos programadores, basta dizer que o código precisa ser claro. Se possível, claro o suficiente para que não se dependa de uma documentação para entendê-lo.

Uma boa referência filosófica sobre o assunto pode ser vista neste link: Self Documenting Code.