“I”, “We” ou Nenhum dos códigos na documentação do código

41

Eu me encontro escrevendo (espero) comentários úteis na documentação do código (C ++) do tipo:

The reason we are doing this is...

A razão pela qual eu uso "nós" em vez de "eu" é porque eu escrevo muito na literatura acadêmica onde "nós" é frequentemente preferido.

Então aqui está a questão. Existe uma boa razão para preferir um ao outro na documentação do código:

  1. Use "Nós": A razão pela qual estamos fazendo isso é ...
  2. Use "I": A razão pela qual estou fazendo isso é ...
  3. Use meu nome: O motivo [my name] fez isso ...
  4. Voz passiva: A razão pela qual isso foi feito é ...
  5. Nem: Faça isso porque ...

Eu escolho # 1 porque estou acostumado a escrever dessa maneira, mas a documentação não é para o escritor, é para o leitor, então estou pensando se adicionar o nome do desenvolvedor é útil ou se isso apenas adiciona outra coisa que precisa ser alterado ao manter o código.

    
por Alan Turing 15.03.2013 / 19:42
fonte

6 respostas

77

Eu iria com:

# 6. Declarativo: ...

Em vez de dizer "A razão pela qual isso foi feito é porque cada Foo deve ter um Bar", basta dizer "Cada Foo deve ter um Bar". Faça o comentário em uma declaração ativa da razão, em vez de uma declaração passiva. Geralmente, é um estilo de escrita melhor em geral, mais adequado à natureza do código (que faz algo), e a expressão the reason this was done não adiciona nenhuma informação. Também evita exatamente o problema que você está encontrando.

    
por 15.03.2013 / 19:51
fonte
23

Eu prefiro nenhum dos dois, e realmente deixaria de lado a frase introdutória e apenas chegaria ao ponto. Eu também tento evitar apenas dizer "isto" porque não dá para saber se o comentário está em sincronia com o código. Em outras palavras, em vez de:

// The reason this was done is to prevent null pointer exceptions later on.

Eu diria:

// Frobnicate the widget first so foo can never be null.

O fato de você estar adicionando um comentário implica que você está declarando um motivo, então você não precisa dizer às pessoas que está explicando o motivo. Apenas torne a questão o mais específica possível, para que eles saibam o mais claramente possível como manter esse código mais tarde.

    
por 15.03.2013 / 19:54
fonte
4

Em C # (e na maioria das ferramentas de documentação em outros idiomas) existe uma diferença entre documentação e comentário in-line. Minha opinião pessoal é que você deve sempre usar comentários formais e declarativos como Bobson e outros sugerem na documentação de uma classe ou membro, mas dentro do código, não há nada de errado em ser menos formal. De fato, às vezes um comentário informal é mais efetivo para explicar por que algo está sendo feito do que uma exposição completa em inglês formal.

Aqui está uma amostra que eu acho que ilustra o ponto.

/// <summary>
/// Takes data from the remote client and stores it in the database.
/// </summary>
/// <param name="data">The data to store.</param>
public void StoreData(ComplexObject data)
{
    // Don't take candy from strangers
    ComplexObject safeData = SanitizeData(data);
    ...
}
    
por 15.03.2013 / 20:52
fonte
2

Outra ideia a ser considerada seria um teste unitário bem elaborado que demonstra por que o código funciona da maneira como funciona no lugar de escrever um comentário descritivo. Isso tem algumas vantagens sobre escrever comentários:

  1. Os comentários nem sempre mudam quando o código é alterado, o que pode gerar confusão mais tarde.

  2. Testes de unidades dão ao mantenedor uma maneira fácil de jogar com o código. Aprender uma nova base de código pode ser muito mais fácil se você tiver unidades individuais que você pode quebrar para observar as mudanças.

Mesmo que esse caminho requeira mais trabalho inicial, o teste de unidade pode ser uma excelente forma de documentação.

    
por 15.03.2013 / 20:22
fonte
1

Bons comentários são difíceis de escrever, e mesmo os melhores comentários são difíceis de ler e compreender. Se o seu comentário for conciso o suficiente para eu absorver e precisar o suficiente para transmitir o que preciso saber sobre o código, não faz qualquer diferença os pronomes que você usa.

Eu odiaria desestimular alguém a comentar seu código porque está preocupado com o caso, o tempo e a pessoa de seus pronomes.

    
por 15.03.2013 / 20:14
fonte
1

The reason I use "we" instead of "I" is because I do a lot of academic writing where "we" is often preferred.

É um estilo ruim, mesmo para trabalhos acadêmicos, a menos que você esteja tentando esconder quem realmente decidiu o ponto exato.

Quanto à sua pergunta específica: eu não deixaria esse comentário, a menos que comece com:

// TODO: clean this up, ...

ou, a menos que explique algo muito importante, isso pode não estar tão claro no código. Nesse caso, faça o comentário o mais breve possível.

    
por 15.03.2013 / 21:05
fonte