"I", "Nós" ou Nem na documentação do código

Eu me pego escrevendo (espero) comentários úteis na documentação de 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 faço muita escrita acadêmica onde "nós" é frequentemente preferido.

Então aqui está a pergunta. Existe um bom motivo 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]disso foi ...
4. Voz passiva: A razão pela qual isso foi feito é ...
5. Nem: Faça isso porque ...

Eu escolhi o número 1 porque estou acostumado a escrever dessa maneira, mas a documentação não é para o escritor, é para o leitor, por isso estou me perguntando se adicionar o nome do desenvolvedor é útil ou se isso apenas acrescenta mais uma coisa que precisa ser ser alterado ao manter o código.

Eu iria com:

# 6 Declarativo: ...

Em vez de dizer "A razão pela qual isso foi feito é porque cada Foo deve ter uma barra", basta dizer "Cada Foo deve ter uma barra". Faça o comentário em uma declaração ativa do motivo, em vez de passiva. Geralmente, é um estilo de escrita melhor, se encaixa melhor na natureza do código (o que faz alguma coisa) e a the reason this was donefrase não adiciona nenhuma informação. Também evita exatamente o problema que você está encontrando.

Eu prefiro nenhum e, na verdade, deixaria de lado essa frase introdutória e chegaria ao ponto. Eu também tento evitar apenas dizer "isso" porque não deixa como saber se o comentário está sincronizado 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ê adicionar um comentário implica que você está indicando um motivo, para que não precise dizer redundantemente às pessoas que está explicando o motivo. Apenas torne o motivo o mais específico possível, para que eles saibam o mais claramente possível como manter esse código posteriormente.

Em C # (e na maioria das ferramentas de documentação em outros idiomas), há uma diferença entre documentação e comentários em linha. Minha opinião pessoal é que você sempre deve 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 errado em ser menos formal. De fato, às vezes um comentário informal é mais eficaz para explicar por que algo está sendo dom 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);
    ...
}

Outra idéia a considerar seria um teste de unidade bem elaborado que demonstre por que o código funciona da mesma maneira que no lugar de escrever um comentário descritivo. Isso tem alguns benefícios em escrever comentários:

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

2. Os testes de unidades oferecem 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 podem ser quebradas para observar quais alterações.

Embora essa avenida exija mais trabalho antecipadamente, o teste de unidade pode ser uma excelente forma de documentação.

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

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

A razão pela qual eu uso "nós" em vez de "eu" é porque faço muita escrita acadêmica onde "nós" é frequentemente preferido.

É um estilo ruim, mesmo para trabalhos acadêmicos, a menos que você esteja tentando esconder quem realmente decidiu esse 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 ser tão claro no código. Nesse caso, faça o comentário o mais breve possível.