Geekly articles weekly

Guia de estilo do Google em C ++. Parte 9

Parte 1. Introdução
...
Parte 8. Nomeação
Parte 9. Comentários
...


Este artigo é uma tradução de parte do guia de estilo do Google em C ++ para o russo.
Artigo original (fork no github), tradução atualizada .

Comentários


Comentários são necessários para o código (se você planeja lê-lo). As regras a seguir descrevem o que você deve comentar e como. Mas lembre-se: embora os comentários sejam muito importantes, o código perfeito é auto-documentado. O uso de nomes "falantes" para tipos e variáveis ​​é muito melhor do que nomes obscuros, que precisam ser escritos nos comentários.

Comente o código levando em consideração os seguintes leitores: programadores que precisam entender seu código. Tenha em mente que você pode ser o próximo leitor!

Estilo do comentário


Use // ou / * * / até que a uniformidade seja violada.

Você pode usar // ou / ** / , no entanto, // é muito preferível. No entanto, sempre alinhe seu estilo de comentário com o código existente.

Comentários no cabeçalho do arquivo


Insira um cabeçalho de licença na parte superior de cada arquivo.

Os comentários no arquivo devem descrever seu conteúdo. Se um arquivo declara, descreve ou testa uma abstração (para a qual já existe um comentário), uma descrição adicional no cabeçalho do arquivo não é necessária. Caso contrário, insira uma descrição do conteúdo na parte superior do arquivo.

Informações legais e lista de autores


Cada arquivo deve conter informações de licença. O formato da descrição depende da licença usada no projeto. Cada licença (Apache 2.0, BSD, LGPL, GPL, etc.) pode ter seus próprios requisitos de design.

Se você fizer alterações significativas no arquivo, considere excluir a lista de autores anterior. Os arquivos atualizados podem não conter mais uma menção a direitos autorais e uma lista de autores.

Conteúdo do arquivo


Se .h declarar várias abstrações, o comentário no cabeçalho do arquivo geralmente descreverá o conteúdo do arquivo e como as abstrações estão relacionadas entre si. Uma, duas frases em um comentário geralmente são suficientes. Informações mais detalhadas são assinadas em outro local (não no cabeçalho do arquivo).

Não duplique os comentários nos arquivos .h e .cc - os comentários se tornam diferentes ao longo do tempo.

Comentários da turma


Cada declaração de classe (exceto as muito óbvias) deve ser acompanhada de um comentário, para que serve a classe e como usá-la.

//   GargantuanTable. // : // GargantuanTableIterator* iter = table->NewIterator(); // for (iter->Seek("foo"); !iter->done(); iter->Next()) { // process(iter->key(), iter->value()); // } // delete iter; class GargantuanTableIterator { ... };

O comentário sobre a classe deve ser suficiente para entender: como e quando usar a classe, requisitos adicionais para o uso correto da classe. Descreva, se necessário, restrições (suposições) na sincronização na classe. Se uma instância da classe puder ser usada em diferentes threads, anote as regras com vários threads.

Você também pode fornecer exemplos curtos de código no comentário da classe para mostrar como é mais fácil usar a classe.

Normalmente, uma classe é declarada / definida em arquivos diferentes ( .h e .cc ). Os comentários que descrevem o uso da classe devem estar próximos à definição da interface. Os comentários sobre os meandros da implementação devem estar próximos ao código dos próprios métodos.

Comentários da função


Comentários sobre uma declaração de função devem descrever o uso da função (exceto nos casos mais óbvios). Comentários sobre a definição da função descrevem a implementação.

Declaração de Função


A declaração de cada função deve ter um comentário (logo antes da declaração), o que a função faz e como usá-la. Um comentário pode ser omitido apenas se a função for simples e seu uso for óbvio (por exemplo, a função de subtrair valores de variáveis). Tente iniciar os comentários com humor indicativo ("Abrir arquivo"). Não é recomendável usar o humor imperativo (“Abrir arquivo”). Um comentário descreve a essência de uma função, não como ela a faz.

No comentário sobre a declaração da função, observe o seguinte:

  • O que é alimentado na entrada da função, que é retornada como resultado.
  • Para uma função membro de uma classe: a instância mantém argumentos de referência,
    Preciso liberar memória.
  • A função aloca a memória que o código de chamada deve excluir.
  • Pode haver argumentos nullptr.
  • A complexidade da função (algorítmica).
  • As chamadas de diferentes segmentos são permitidas ao mesmo tempo? E a sincronização?

Um exemplo:

 //    .    //   .    //    GargantuanTable  . // //      . // //    : // Iterator* iter = table->NewIterator(); // iter->Seek(""); // return iter; //         , //    NewIterator()     . Iterator* GetIterator() const;

No entanto, não mastigue coisas óbvias.

Ao documentar funções sobrecarregadas, faça as principais alterações persistentes em comparação com a função original. E se não houver alterações (o que acontece com frequência), comentários adicionais não serão necessários.

Ao comentar sobre construtores e destruidores, lembre-se de que o leitor de código conhece seu propósito. Portanto, o comentário do tipo "destrói esse objeto" é estúpido. Você pode descrever o que o construtor faz com argumentos (por exemplo, alterar a propriedade dos ponteiros) ou que tipo de operações de limpeza o destruidor faz. Se tudo estiver claro, não comente nada. Em geral, os destruidores geralmente não têm comentários (quando declarados).

Definição de Função


Se houver algum truque na implementação da função, você poderá adicionar um comentário explicativo à definição. Nele, você pode descrever truques com o código, fornecer uma visão geral de todas as etapas dos cálculos, explicar a escolha dessa ou daquela implementação (especialmente se houver melhores alternativas). Você pode descrever os princípios da sincronização de código (aqui bloqueamos, mas aqui envolvemos o peixe).

Observe que você não deve repetir o comentário sobre a declaração da função (de um arquivo .h ou similar) .É possível descrever brevemente o que a função faz, mas o principal é saber como ela é executada.

Comentários sobre Variáveis


De uma maneira boa, o nome da variável deve dizer imediatamente o que é e por quê.No entanto, em alguns casos, são necessários comentários adicionais.

Membro de dados da classe


O objetivo de cada membro da classe deve ser óbvio. Se houver sutilezas não óbvias (significados especiais, vínculos com outros membros, restrições à vida) - tudo isso precisa ser comentado. No entanto, se o tipo e o nome forem suficientes - você não precisará adicionar comentários.

Por outro lado, descrições de valores especiais (e não óbvios) (nullptr ou -1) serão úteis. Por exemplo:

 private: //       // -1 - ,         int num_total_entries_;

Variáveis ​​globais


Todas as variáveis ​​globais devem ser comentadas sobre seus propósitos e (se não óbvias) por que elas devem ser globais.

 //   ,     const int kNumTestCases = 6;

Comentários sobre a implementação


Comente a implementação de uma função ou algoritmo no caso de partes de código não óbvias, interessantes e importantes.

Comentários descritivos


Blocos de código complexos ou fora do padrão devem ser precedidos por um comentário. Por exemplo:

 //    2.  x    for (int i = 0; i < result->size(); ++i) { x = (x << 8) + (*result)[i]; (*result)[i] = x >> 1; x &= 1; }

Comentários de linha


É aconselhável complementar as linhas de código com significado não óbvio com um comentário (geralmente localizado no final da linha) .Este comentário deve ser separado do código por 2 espaços. Por exemplo:

 //   ,    mmap_budget = max<int64>(0, mmap_budget - index_->length()); if (mmap_budget >= data_size_ && !MmapData(mmap_chunk_bytes, mlock)) return; //

Observe que existem 2 comentários no bloco de código: um descreve o que o código faz, o outro lembra que o erro já está no log se houver um retorno da função.

Comentários sobre argumentos de função


Ao atribuir um argumento a uma função não é óbvio, considere as seguintes opções:

  • Se o argumento for um valor fixo (constante literal) e esse valor
    usado em diferentes blocos de código (e entende-se que esse valor é a mesma coisa)
    você deve criar uma constante e usá-la explicitamente.
  • Talvez você deva substituir o argumento do tipo bool por
    enumeração enum . Isso tornará o argumento autodeterminado.
  • Para funções que usam várias opções de configuração nos argumentos, você pode
    crie uma classe (ou estrutura) separada que combine todas as opções. E passar para funcionar
    uma instância desta classe.
    Essa abordagem tem várias vantagens: as opções são indicadas por nomes, o que explica
    seu propósito. O número de argumentos na função é reduzido - o código é mais fácil de escrever e ler.
    E se você precisar adicionar mais opções, não precisará alterar a chamada de função.
  • Em vez de expressões complexas nos argumentos, use uma variável intermediária à qual você atribui uma expressão.
  • Como último recurso, escreva comentários no local da chamada para esclarecer a finalidade dos argumentos.

Considere os seguintes exemplos:

 //    ? const DecimalNumber product = CalculateProduct(values, 7, false, nullptr);

Vamos tentar pentear o código:

 ProductOptions options; options.set_precision_decimals(7); options.set_use_cache(ProductOptions::kDontUseCache); const DecimalNumber product = CalculateProduct(values, options, /*completion_callback=*/nullptr);

O que não fazer


Não explique o óbvio. Em particular, não há necessidade de explicar coisas óbvias para uma pessoa que conhece C ++. Em vez disso, você pode descrever por que esse código o faz (ou mesmo torná-lo auto-descritivo).

Compare:

 //    . <-- :  ! auto iter = std::find(v.begin(), v.end(), element); if (iter != v.end()) { Process(element); }

Com isso:

 //  (Process) "element"     auto iter = std::find(v.begin(), v.end(), element); if (iter != v.end()) { Process(element); }

O código autoexplicativo não precisa de comentários.
O comentário no código acima pode ser geralmente óbvio (e não necessário):

 if (!IsAlreadyProcessed(element)) { Process(element); }

Pontuação, ortografia e gramática


Preste atenção à pontuação, ortografia e gramática: é muito mais fácil ler comentários escritos corretamente.

Os comentários devem ser escritos como uma história: com o arranjo correto de letras maiúsculas e sinais de pontuação. Na maioria dos casos, frases completas são mais fáceis de entender do que fragmentos de frases. Comentários breves, como linha por linha, podem ser menos formais, mas ainda devem seguir um estilo comum.

Embora a ênfase excessiva do revisor de código no uso de vírgulas em vez de ponto e vírgula possa ser um pouco irritante, é importante manter um alto nível de legibilidade e compreensão. Pontuação, ortografia e gramática adequadas contribuem muito para isso.

Comentários TODO


Use os comentários do TODO para obter um código temporário ou uma solução boa o suficiente (intermediária, não perfeita).

O comentário deve incluir a linha TODO (todas as letras maiúsculas), seguida pelo nome, endereço de email, ID do defeito ou outras informações para identificar o desenvolvedor e a natureza do problema para o qual o TODO está gravado.O objetivo desta descrição é encontrar mais detalhes posteriormente. não significa que o programador especificado irá resolver o problema. Portanto, quando você cria o TODO , o nome usual é o seu nome.

 // TODO(kl@gmail.com):  "*"  . // TODO(Zeke)   . // TODO(bug 12345):   " ".

Se o seu TODO parecer "Vamos fazer diferente no futuro", indique uma data específica ("Corrija em novembro de 2005") ou um evento ("Exclua esse código quando todos os clientes processarem solicitações XML").

Nota:
- Os links podem levar a seções do manual que ainda não foram traduzidas.
- uma discussão de questões gerais é melhor feita na Parte 1. Introdução

Source: https://habr.com/ru/post/pt480424/

More articles:


All Articles