Nota: esse foi um artigo que escrevi pra Revista Espírito Livre, mas a edição nunca saiu. Mantive no mesmo formato e estilo que sairia na revista.
Algumas pessoas podem não acreditar ou até mesmo pensar que é loucura mas o software livre trata sobre... software! Nesse momento imagino já algumas pessoas revoltadas jogando cadeiras e ameaçando colocar fogo nas lixeiras mas infelizmente o software livre é sobre software. O software livre nos dá as diretivas pra termos um software que seja livre, mas não diz nada sobre como escrever esse software. Nenhuma direção, nada. Apenas sobre sua licença.
E software, apesar de ser uma forma de comunicação com um computador que interpretará as diretivas como uma linguagem de máquina e mandará sua CPU executar os passos descritos, pode e deve ser legível por seres humanos. Sim! Software é uma forma de escrita e como tal é imperativo para que seja lido e entendido tanto por CPUs quanto por humanos.
Existe então um movimento chamado "software craftmanship". A tradução remonta aos forjadores de armadura da idade média (não que o termo venha dessa época, é apenas a referencia feita). Uma tradução mais próxima seria algo como "forjadores de programação". Esse movimento tem seu manifesto explicitado em:
https://manifesto.softwarecraftsmanship.org/#/pt-br
Descrevendo o mesmo literalmente aqui:
Como aspirantes a verdadeiros Artesãos de Software, estamos ampliando as fronteiras da qualidade no desenvolvimento profissional de programas de computadores através da prática e ensinando outros a aprender nossa arte. Graças a esse trabalho, valorizamos:
Não apenas software em funcionamento,
mas software de excelente qualidade
Não apenas responder a mudanças,
mas agregar valor de forma constante e crescente
Não apenas indivíduos e suas interações,
mas uma comunidade de profissionais
Não apenas a colaboração do cliente,
mas parcerias produtivas.
Sendo assim descobrimos, que para atingir os objetivos à esquerda, os que estão à direita são indispensáveis.
A tradução existente no site usa o termo "artesãos de software" mas eu prefiro como "forjadores de software". Preciosidades linguísticas à parte, é possível ver que o foco é que todo código seja lido e interpretado por pessoas.
Um dos pais desse movimento é Robert C. Martin, ou como é mais conhecido, uncle Bob. Além de ter escrito os livros que são referências para clean code, Clean Code: A handbook of Agile Software Craftsmanship[1] e The Clean Coder: A Code of Conduct for Professional Porgrammers[2], ele também tem uma série de vídeos a respeito que ajudam a entender e aplicar os conceitos de clean code. O primeiro episódio[3] está disponível gratuitamente.
Clean code é uma prática ativa de software e um artigo somente não é o suficiente pra cobrir todo o assunto. Então descreverei apenas uma pequena parte referente sobre como escrever código de uma forma prática. Usarei shell script como exemplo por ser uma das primeiras linguagens de programação pra quem inicia no mundo Unix e ter uma curva de aprendizado mais baixa se comparada com linguagens como C.
Variáveis
Em clean code a ideia é escrever o código próximo da linguagem falada. Então algumas dicas são usar variáveis com nome significativo e lembrando substantivos. Então um loop for como esse:
for f in *txt
do
...
done
A variável "f" é claramente um padrão não desejado. O que significa "f"? De acordo com os fundamentos o melhor seria:
for fileName in *txt
do
...
done
Eu escolhi manter o padrão em inglês, mas claro que ali poderia ser "nomeArquivo". Eu usei a notação chamada "camelCase". Poderia ter usado for formato "file_name", snake case, mas esse tipo de detalhismo não é relevante pra clean code. O melhor seria seguir o padrão que o time usa no código em geral. No meu time trabalhamos muito com a linguagem go, que usa a forma "camelCase" e por isso acabo adotando no meu código.
Outra regra pras variáveis é tentar decidir se o nome é longo ou curto baseado em seu escopo de uso. Se a variável é muito usado, o melhor é ter um nome longo e bem descritivo. Se seu uso é curto, seu nome também pode ser curto. Então se dentro de um programa existir uma pequena função que apenas faça um sleep:
for i in $(seq 1 10)
do
echo $i
done
Esse não é lá um código muito útil, mas ilustra que pra um pequeno loop uma variável "i" pode ser aceita. Sempre lembando que depende do escopo de uso da variável.
Funções
Já as funções em clean code seguem a recomendação inversa. Se for muito usada no escopo do programa, o melhor é usar um nome mais curto. Se for pouco usada, um nome mais longo. E sempre usar um verbo pra funções. Ampliando o código do exemplo anterior, é possível criar uma função que retorne os nomes de todos os arquivos passados em seu argumento como padrão, algo como "*.txt". Como o exemplo é em shell script, não é possível usar return, mas um "echo" diretamente pra ler a resposta.
O código então poderia ser:
getFileNames() {
pattern=$1
for fileName in *$pattern
do
echo $fileName
done
}
allTXTFiles=$(getFileNames txt)
Então a função vira um "pegar os nomes de arquivos". O substantivo "allTXTFiles" tem o verbo "pegar os nomes de arquivos txt", ou ficando mais próximo da língua falada: "todos os arquivos TXT" é "pegar os nomes dos arquivos txt".
Booleanos
Booleanos são variáveis com valores sim ou não, verdadeiro ou falso. Seu uso em clean code pode ser traduzido como pergunta. Então parâmetros booleanos podem ser valores como "temperatura é alta", "isTemperatureHigh".
Um pequeno exemplo com um script pra verificar se é fim de semana.
getWeekend() {
weekDay=$(date +%a)
echo $weekDay | egrep -q "Sun|Sat"
echo $?
}
isWeekend=$(getWeekend)
if [ $isWeekend ]; then
echo "This is weekend."
else
echo "This is a working day."
fi
Comentários
Os comentários em código significam que ou seu código está tão mal escrito que precisa ter explicação. Então em clean code deve-se evitar o uso de comentários, mas se forem necessários, que sejam extremamente descritivos.
Então um exemplo de comentário pro meu código acima.
# it returns 0 for Sundays or Saturdays, 1 for every other day.
getWeekend() {
weekDay=$(date +%a)
echo $weekDay | egrep -q "Sun|Sat"
echo $?
}
Meu comentário não descreve a função, que o nome já faz isso. Apenas melhora o entendimento do que voltará como parâmetro.
Um exemplo real
Eu pedi um exemplo pra aplicar os princípios de clean code às pessoas do grupo de shell script no telegram[4]. Agradeço então ao usuário @fonini por ter fornecido seu código. O código em questão é esse (apenas uma parte do código):
ts="$(date +%Y%m%d.%H%M%S.%N)" # timestamp
if [[ ! -v DEBUGFILE ]]; then
printf "Set DEBUGFILE first.\n" 1>&2
exit 1
fi
if (( $# < 1 )); then
printf '%s\n%s\n' \
"usage: DEBUGFILE=filename debug format [args]" \
" e.g.: export DEBUGFILE=log.txt"
exit 2
fi
O que pode ser melhorado nesse código? Segue o que seria uma aplicação dos princípios de clean code no sell script.
checkForDebug(){
if [[ ! -v DEBUGFILE ]]; then
printf "Set DEBUGFILE first.\n" 1>&2
exit 1
fi
}
printUsage() {
printf '%s\n%s\n' \
"usage: DEBUGFILE=filename debug format [args]" \
" e.g.: export DEBUGFILE=log.txt"
}
validateNumberArguments() {
totalArguments=$1
if (( $totalArguments < 1 )); then
printUsage
exit 2
fi
}
timestamp="$(date +%Y%m%d.%H%M%S.%N)"
checkForDebug
numberOfArguments=$#
validateNumberArguments $numberOfArguments
Não mentirei que clean code é fácil. É uma disciplina: é preciso praticar o tempo todo pra conseguir aplicar. No começo não é fácil, mas com o tempo seu código vai melhorando a legibilidade. E isso é apenas uma pequena parte de clean code. Tentarei descrever mais nas próximas edições.
|
Sobre o autor:
|
|
Referências:
[1] Clean Code: A Handbook of Agile Software Craftsmanship - http://hl.eng.br/6cX
[2] The Clean Coder: A Code of Conduct for Professional Programmers - http://hl.eng.br/6cW
[3] Clean Code: Fundamentals, Episode 1 - https://cleancoders.com/video-details/clean-code-episode-1
[4] Shell Script (#!/bin/bash) - https://t.me/shellbr
