Código limpo parte 2

Continuando a falar sobre código limpo segue abaixo um resumo de mais alguns capítulos do livro Código limpo de Robert C. Martin.   Aqui falaremos sobre

1. Comentários;
2. Formatação;
3. Tratamento de erros

  1 - Comentários: Segundo o próprio autor do livro o comentário deve ser evitado ao máximo, pois diferentemente do código o comentário geralmente não é atualizado conforme as modificações no sistema, ou seja, entre existir um comentário ruim e não ter nenhum, melhor não ter nenhum. Tipos de comentários ruins: quando um cometário é impreciso ou redundante torna-se um comentário ruim. Veja abaixo um exemplo de comentário redundante seguido de um comentário impreciso.

/**
* @return
*/
function verificaSessao()
{
    if (isset($_SESSION)) {
        return true;
    }

    return false;
}

  Note que o comentário não menciona sequer o tipo de retorno. Neste código está bem simples de entender, mas em caso de um método mais complexo, sem um comentário, um nome do método bem explicativo ou mesmo a definição do tipo de retorno, fica difícil de saber qual é a saída.   Agora o comentário impreciso   Viu só como o comentário pode se tornar impreciso rapidinho? Note que na linha 17 informa que buscará os dados da compra, no entanto, tempos depois outro programador ou você mesmo adicionou os dados do produto, note que o comentário permaneceu no mesmo local no entanto a variável que o mesmo referenciava está agora na linha 19. Isto é um exemplo muito óbvio pois estamos falando de apenas um fragmento de código, mas quando falamos de um sistema completo ou de vários programadores trabalhando no mesmo projeto este erro é muito comum de se encontrar. Comentários de autoria: Normalmente em fabricantes de software é comum encontrarmos comentários informando o nome da empresa, programador que criou o código, data de criação, versão entre outros. Isto é normal, agora há quem coloca comentários sobre direitos autorais gigantescos como por exemplo a licença GPL. Quando for este o caso procure ao invés de copiar e colar todo seu conteúdo o que pode chegar facilmente a algumas centenas de linhas, colocar somente a referência do mesmo, caso o "leitor" esteja interessado o mesmo procurará o documento através do link que você forneceu no comentário. Justifique-se no código: Melhor que ter um comentário explicando o que tal trecho do código faz é deixar seu código dizer, veja o exemplo nas imagens a seguir:   Agora veja a função realizando exatamente a mesma coisa, mas com duas diferenças: foram removidos os comentários e o código está explicando sua finalidade.   Comentários de justificativa: Um bom tipo de comentário pois serve para você desabafar! Por exemplo: você tentou desesperadamente finalizar a integração com todos os tipos de pagamento que a API fornece, no entanto por questão de tempo hábil o mesmo não foi possível. Com isso você adiciona um comentário informando do que já realizou e o que ainda falta para poder trabalhar em um outro momento ou mesmo passar a tarefa a outro programador. Comentários TODO: Esse é um tipo de comentário que, segundo o autor do livro, deveria ser um dos únicos a existir pois o mesmo serve como uma "lista de tarefas" a serem realizadas. Informações excessivas: Evite adicionar discussões em fóruns onde você localizou a solução para determinado problema, informe a penas o link do post e nome do autor que postou sua solução.   2 - Formatação: Pode até parecer obvio demais mas muitos programadores iniciantes não tem muito bom hábito de formatar seu código corretamente, isso pode gerar dificuldades na leitura e consequentemente estar passivo a erros. A imagem a seguir mostram um mau exemplo de formatação.     Metáfora do jornal: Quando você lê um artigo de jornal espera primeiro ver um resumo e se o conteúdo lhe interessar prosseguir com a leitura vendo nomes, datas entre outros, da mesma forma deve estar seu código, ou seja, ao bater os olhos no seu código um programador deve ver primeiramente o que é mais relevante, e normalmente o que ele está procurando. Um exemplo disso é uma classe com a responsabilidade sobre usuários. Esta classe deve conter logo em seu início os métodos cruciais como obtenção de dados, login e alterações, para em seguida virem os métodos de baixo nível. Ou seja, primeiro vem seus métodos públicos que qualquer parte de seu código pode utilizar para em seguida virem os métodos privados que somente esta classe possui acesso.   3 - Tratamento de erros: Sempre lance excessões ao invés de retornar códigos de erro, afinal de contas para o usuário do seu sistema pouco importa o código de erro que o mesmo gerou. Para ele interessa apenas uma única coisa, que o sistema funcione! Curto e grosso não? Não! Quem deve se atentar a códigos de erros deve ser o programador. Mas então como fazer para que o código permaneça limpo ao mesmo tempo que eu oculto dados de programação de meus usuários? Com o tratamento de erro, mais especificamente utilizando a estrutura try/catch você garante que ao encontrar erro em um determinado processo o mesmo pode ser interrompido sem causar travamento de seu sistema pois dentro das chaves "{}" do try você espera que tudo esteja funcionando normalmente, caso isso não ocorra entra nas chaves "{}" do catch e aí você pode simplesmente pode exibir uma mensagem de erro genérica (lançar excessão) ao usuário ao mesmo tempo que grava um log detalhado contendo código e mensagem do erro. Parece uma tarefa árdua né, ficar tratando erro em todos os pontos cruciais para seu sistema, e é! Por isso mesmo que o tratamento de erro já deve "nascer" com o código. Motivo: depois de tudo pronto você provavelmente terá um dos dois pensamentos, se não os dois. Primeiro pensamento - está funcionando então não há necessidade de eu criar os tratamentos de erros. Segundo pensamento - Nossa, já está tudo tão complexo e eu ainda vou ter que mexer em tudo isso? Não não, deixa como está mesmo. Provavelmente você se identificará com pelo menos um dos pensamentos apresentados, então mãos à obra e crie tratamentos de erros desde o início do seu código, valerá a pena!   Lei também: Código limpo parte 1