6. Comentários - Tecprog-voID/voID GitHub Wiki

Índice

Comentários devem estar em inglês;

6.1 Comentário de 1 Linha

Para comentários de uma única linha devem ser utilizadas barras duplas. Deve haver um espaço entre a última barra dupla e o início do comentário.

Exemplo:

// image handling

6.2 Comentário de 2 ou Mais Linhas

Para comentários de 2 ou mais linhas, deve ser utilizada a barra com o asterisco (/* */), que deve estar sozinha em uma linha.

Exemplo:

/*
    auto map = new GameObject("Map", new Vector(-5250 ,-5000),10500,10500);
    // Renderer
    auto mapImage = new Image("assets/world.png", 0, 0, 3500, 3500);
    auto mapRenderer = new Renderer(map, mapImage);
*/

6.3 Comentário de Arquivo

Todo arquivo deve ter um comentário, nas primeiras linhas do arquivo. Este deve começar com /** e terminar com */, ambos em uma linha separada. Em seguida, devem ser apresentadas, indentadas, as seguintes informações, nesta ordem:

  1. Nome do arquivo, precedido de @file;
  2. Descrição do propósito e conteúdo do arquivo, precedido de @brief;
  3. Informações sobre a licença do arquivo, precedido de @copyright;
  4. (Opcional) Outros detalhes pertinentes do arquivo, precedido de @details, caso seja necessário.

Sempre que um comentário for formado por uma ou mais frases, ele deve ser iniciado com letra maiúscula e terminado com um ponto final.

Exemplo:

/**
    @file GameObject.hpp
    @brief Class that represents all the game objects, like name and velocity.
    @copyright LGPL. MIT License.
*/

#ifndef __GAME_OBJECT__
#define __GAME_OBJECT__

#include "Engine/Component.hpp"
#include "Engine/sdl2include.hpp"

6.4 Comentário de Função/Procedimento

Toda função ou procedimento deverá ter um comentário imediatamente acima dela. Deve começar com /** e terminar com */, ambos em uma linha separada. Em seguida, deverão ser apresentadas, indentadas, as seguintes informações, nesta ordem:

  1. Breve resumo da função/procedimento e o por quê dela, precedido de @brief;
  2. Todos os parâmetros da função/procedimento (caso ela tenha), precedido de @param seguido do nome do parâmetro. Junto ao @param, entre [ ], deverá ser informado se é um parâmetro de entrada ([in]), de saída ([out]), ou ambos ([in/out]). Por fim, se for o caso, deverão ser fornecidas informações sobre os parâmetros tais como: unidade de medida, intervalo de valores numéricos, enums, entre outros que forem realmente necessários.
  3. O que ele retorna, precedido de @return, caso seja uma função. Se for procedimento, este item não deverá ser colocado.
  4. (Opcional) Outros detalhes pertinentes da função/procedimento, precedido de @details, caso seja necessário.

Sempre que um comentário for formado por uma ou mais frases, ele deve ser iniciado com letra maiúscula e terminado com um ponto final.

Exemplo:

/**
    @brief Set the color of the circle rendered.
    @param[in] red Red color integer value. The range is from 0 to 255.
    @param[in] green Green color integer value. The range is from 0 to 255.
    @param[in] blue Blue color integer value. The range is from 0 to 255.
    @param[in] alpha Transparency integer value. The range is from 0 to 255, and
    the lower is the value, bigger is the transparency.
*/

6.5 Comentário de Variável

A finalidade de cada variável de instância deve ser clara. Se houver quaisquer invariantes não claramente expressos pelo tipo e nome, eles devem ser comentados. No entanto, se o tipo e o nome forem suficientes, nenhum comentário é necessário.
Exemplo:

    // adpted image properties
    Vector *m_pivot = nullptr;
    bool m_horizontalFlip = false;

6.6 Comentário de Parágrafo de Código

Escrever comentários sobre a intenção do código e pensar como se fosse dar um nome de função para o conjunto de linhas. Escrever comentário sobre o por que em vez de como. Utilizar o comentário para preparar o leitor para o que vem a seguir.

Exemplo:

    // Get all scene game objects.
    m_gameObjects = scene->GetAllGameObjects();
    if (m_gameObjects.empty()) {
        return;
    }

6.7 Comentário de Estrutura de Repetição/ Controle

Escrever comentários sobre a estrutura de repetição ou de controle, indicando o seu propósito. O comentário deve ser na linha anterior do início da estrutura. Ao fim da estrutura deve ter outro comentário informando o seu fechamento, caso o corpo da estrutura seja muito grande de forma que facilite a visibilidade.

Exemplo:

    // copy input field up to comma
    while ( ( *inputString != ',' ) && ( *inputString != END_OF_STRING ) ) {
       *field = *inputString;
       field++;
       inputString++;
       ...
    } // while -- copy input field