Tópico 05 - Comentários

Tópico 05 - Comentários

Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 05 - Comentários

Comentários

Comentários são utilizados desde os primórdios da programação para documentar o código.

É uma forma de comunicação que é usada exclusivamente entre programadores.

Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 05 - Comentários

"Comentários são sempre fracassos."
Clean Code

Um comentário pode ser uma ferramenta útil para explicar o que está acontecendo em um trecho de código, mas deve ser usado com moderação.

O comentário existe para explicar aquilo que não conseguimos fazer com a linguagem de programação.

Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 05 - Comentários

Comentários compensam código ruim

Quanto mais bem escrito o código, menor a necessidade de comentários.

Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 05 - Comentários
// Verifica se o funcionário é elegível para benefícios completos
if ((employee.flags & HOURLY_FLAG) && (employee.age < 65))
Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 05 - Comentários
if (employee.isEligibleForFullBenefits())
Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 05 - Comentários

Licenças de Software

Por questões legais, muitos projetos precisam incluir informações sobre a licença de software em cada um dos arquivos do projeto.

Felizmente, a maioria dos editores de código possui plugins que adicionam essas informações automaticamente ou escondem enquanto o usuário trabalha no arquivo.

Onde for possível, é recomendado que os termos da licença sejam apresentados num documento externo.

Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 05 - Comentários
/**************************************************************************/
/*  main.h                                                                */
/**************************************************************************/
/*                         This file is part of:                          */
/*                             GODOT ENGINE                               */
/*                        https://godotengine.org                         */
/**************************************************************************/
/* Copyright (c) 2014-present Godot Engine contributors (see AUTHORS.md). */
/* Copyright (c) 2007-2014 Juan Linietsky, Ariel Manzur.                  */
/*                                                                        */
/* Permission is hereby granted, free of charge, to any person obtaining  */
/* a copy of this software and associated documentation files (the        */
/* "Software"), to deal in the Software without restriction, including    */
/* without limitation the rights to use, copy, modify, merge, publish,    */
/* distribute, sublicense, and/or sell copies of the Software, and to     */
/* permit persons to whom the Software is furnished to do so, subject to  */
/* the following conditions:                                              */
/*                                                                        */
/* The above copyright notice and this permission notice shall be         */
/* included in all copies or substantial portions of the Software.        */
/*                                                                        */
/* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,        */
/* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF     */
/* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. */
/* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY   */
/* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,   */
/* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE      */
/* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.                 */
/**************************************************************************/
Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 05 - Comentários

Explicação da Intenção

Um comentário que explica a razão de um trecho de código ao invés de descrever como ele funciona, por vezes, é útil:

// os espaços em branco são substituídos por %20 para evitar erros de URL
String url = rawUrl.replaceAll("\\s+", "%20");
Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 05 - Comentários

Alerta de Consequências

Partes críticas de um código também podem ser comentadas para alertar sobre as consequências de uma mudança.

// Executar esse teste apenas se tiver tempo disponível
/* 
public void _testWithReallyBigFile() {
    // ...
}
*/
Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 05 - Comentários

Comentários TODO

Comentários que indicam que uma tarefa ainda precisa ser feita geralmente são marcados com TODO.

Essa prática é comumente usada para indicar que uma tarefa ainda não foi implementada.

Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 05 - Comentários

Documentação de API

Códigos que serão distribuídos devem ter documentação de API. Geralmente utiliza-se ferramentas como Javadoc ou Doxygen para gerar documentação de API, que deve ser mantida atualizada e devem ser incluídas no código.

Não é necessário gerar documentação de API se o código não for distribuído.

Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 05 - Comentários

Murmúrios

Comentários que adicionam a experiência pessoal do programador e que não auxiliam na compreensão do código devem ser suprimidos.

Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 05 - Comentários

Comentários Redundantes

Em ambientes de aprendizagem, é comum que os alunos adicionem comentários redundantes para ajudar a entender o código.

Pra desenvolvedores mais experientes, não é necessário comentar o código, pois ele deve ser autoexplicativo.

Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 05 - Comentários

Comentários Enganosos

Poucas coisas são mais destastosas do que comentários que documentam funcionalidades do código que não existem ou que não funcionam.

Um comentário enganoso deve ser alterado ou removido assim que possível.

Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 05 - Comentários

Comentários Imperativos

Com exceção de documentação de API, comentários não devem ser obrigatórios.

O uso de comentários deve ser moderado pelo bom senso do programador.

Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 05 - Comentários
/*
Esta variável name é usada para armazenar o nome do ambiente.
O ambiente deve ser configurado da seguinte forma:
    - development
    - test
    - production
Para alterar o ambiente, é necessário ir até
as configurações de ambiente do sistema
e alterar o valor da variável de ambiente.
O valor padrão é development.
Em caso de problemas em alterar o valor da variável de ambiente,
é necessário reiniciar o sistema.
*/
String name = getEnviromentVariable("name");
String statusCode = getEnviromentVariable("status_code");
String statusMessage = getEnviromentVariable("status_message");

Comentários Longos

Comentários devem ser objetivos e diretos.

Um bloco de comentário que tende a crescer com o tempo é um forte indicativo de que ele não é bem vindo em um código.

Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 05 - Comentários

Comentários Ruidosos

Comentários excessivos adicionam ruído ao código, que impedem de entender funcionalidades ou nomenclaturas simples.

Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 05 - Comentários

Substitua comentários por funções

Quando existe a necessidade de comentar um trecho de código, a primera ação é avaliar a possibilidade de deixar a função mais clara ou construir uma nova função.

Comentários que explicam o que acontece em um trecho de código são, geralmente, reflexos de um código ruim.

Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 05 - Comentários
// Calcula o imposto de renda de um funcionário
// Retorna o valor do imposto calculado
public double calcularImpostoDeRenda(double salario) {
    // Primeiro verifica se o salário é maior que o limite de isenção
    // Depois calcula o imposto com base na faixa salarial
    if (salario <= 2500) {
        return 0; // Isento de imposto
    } else if (salario <= 5000) {
        return salario * 0.1; // 10% de imposto
    } else {
        return salario * 0.2; // 20% de imposto
    }
}
Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 05 - Comentários
public double calcularImpostoDeRenda(double salario) {
    if (isIsento(salario)) {
        return 0;
    } else if (isFaixaIntermediaria(salario)) {
        return calcularImpostoFaixaIntermediaria(salario);
    } else {
        return calcularImpostoFaixaSuperior(salario);
    }
}
Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 05 - Comentários

Marcadores

Não use comentários para marcar trechos de código em seções.

Se um código é muito longo, é provável que ele possa ser dividido em arquivos menores.

Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 05 - Comentários
public class Foo {
    // ------- ATRIBUTOS -------
    private String name;
    // ------- CONSTRUTOR -------
    public Foo(String name) {
        this.name = name;
    }
    // ------- GETTERS -------
    public String getName() {
        return name;
    }
    // ------- SETTERS -------
    public void setName(String name) {
        this.name = name;
    }
}
Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 05 - Comentários

Posição dos Comentários

Um bom comentário deve estar posicionado logo acima do código que ele descreve.

Em alguns casos, podemos ter comentários posicionados no final do código, mas devemos tomar cuidado com a legibilidade do código.

Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 05 - Comentários
public String convertDatetimeToString(Date date) {
    SimpleDateFormat sdf = new SimpleDateFormat();
    return sdf.format(date);
} // O padrão do SimpleDateFormat é "dd/MM/yyyy"
Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 05 - Comentários

Comentários vs Controle de Versão

  • Autoria
  • Data de Criação / Atualização
  • Linhas editadas
Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 05 - Comentários
// Autor: John Doe
// Data: 2023-07-28
// Linhas editadas: 1-5, 10-15
public class Foo {
    // ...
    // <- Última linha editada
}
Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 05 - Comentários

Material de Apoio

Clean Code - Professor Ramon Venson - SATC 2025.2