Uma etapa bem sedimentada nos conceitos de engenharia de software é a documentação. Já vi muita documentação de sistemas e muito trabalho sendo contratado que exigia a criação de uma. Há uma documentação, porém, pra qual muitas vezes não é dada a devida atenção, seja em contratos comerciais, seja na verificação do produto final, mesmo que gerado internamente numa empresa ou por uma pequena equipe: comentários e código bem escrito.

Comentários - DICA GERAL
* regras de negócio - um código bem comentado pode conter até as regras de negócio que estão normalmente num documento de especificação. Isso facilita a manutenção atualizada. No momento que a regra for alterada na prática, o programador está ali e pode ver que é necessário alterar o comentário.

• lógica - em outras situações o programador faz uma lógica mais complexa e não a explica em comentários. Isso é muito ruim, tanto para trabalho em equipe quanto para o próprio programador, quando tem que mexer nesse código meses depois.

Código bem escrito

• identação - além de comentários, um código bem identado ajuda na compreensão da lógica. Shell não exige identação, o que pode ser uma armadilha - DICA GERAL
• nomes de variáveis - dê nomes de variáveis que indiquem seu significado e uso - DICA GERAL
• nomes de variáveis minúsculos - é um hábito de muitos programadores Shell o uso de nomes maiúsculos para variáveis. Isso aumenta o risco de acertar o nome de uma variável ambiente, essas sim, tradicionalmente maiúsculas.

Cabeçalho - DICA GERAL \\Use um cabeçalho padrão nos seus códigos. Um bom cabeçalho pode conter:

• Descrição geral do que aquele código faz
• Nome do autor e data de criação
• Histórico de alterações com comentários sobre cada uma
• Resumo de parâmetros que recebe e que retorna

• Teste de parâmetros de entrada e mensagem de uso correto
• Tratamento de exceções
• Configurações
• Funções
• Programa principal
• Identação
• Modularização

• Refatoração para viabilizar
• Script testador

• Controle de versão