Para comentários sobre controle de versão, o que outros usuários fazem / recomendam - tempo passado ou presente?

Ou seja,

• Alterado x para ser y.
• ou
• Alterando x para ser y.

Os comentários devem ser lidos no contexto, portanto:

Presente

Para comentários de origem acima de um método ou antes que ocorra algum comportamento:

// This function does X
function doX() { ... }

Passado

Para comentários de origem após a ocorrência de algum comportamento

function doX() {
    widget.doY()
    // did Y to widget to prepare it for Z
    ...
}

E para enviar mensagens

função X alterada

Exemplo misto:

// This function does X
function doX() {
    widget.doY()
    // did Y to widget to prepare it for Z
    ....
}

Passado - uma vez que quem lê no futuro se refere ao ato da mudança como aconteceu no passado.

Escrever algo como "Alterando" implica que você está atualmente no processo de fazer a alteração e que o código pode não estar concluído.

nota: Pessoalmente, só coloco comentários de alteração quando ocorre uma mudança drástica.

Os comentários são coisas estáticas, portanto, eles devem apresentar o estado do programa como está , e não como será. Para responder sua pergunta específica, seria mais apropriado usar o tempo passado .

No entanto, esse tipo de comentário é mais adequado ao seu sistema de controle de versão. O controle de versão faz um trabalho de rastreamento de alterações muito melhor do que os comentários manuais. Com os sistemas de controle de versão, é mais apropriado documentar no tempo presente, pois esses comentários se aplicam no momento em que a alteração é confirmada. Mas, ambos irão funcionar.

Eu recomendo que os únicos comentários no seu código sejam o necessário para entender o próprio código - o objetivo, a lógica de negócios e os casos excepcionais. Deixe a documentação do conjunto de alterações no seu sistema de controle de versão. Se você não estiver usando um VCS, comece agora. Existem vários VCS de alta qualidade que são gratuitos (Subversion, Mercurial, Git, etc.).

Eu uso o presente imperativo, então algo como:

Mude "x" para "y"

Isso é recomendado pelos desenvolvedores do Git:

• o corpo deve fornecer uma mensagem de confirmação significativa, que:
  • usa o imperativo, presente: "mudança", não "alterado" ou "mudanças".

Pode parecer um pouco estranho no começo, mas se você pensa em um commit como um patch que faz alguma coisa, faz mais sentido. (Isso é especialmente verdade em um DVCS como o Git, no qual você recebe conjuntos de alterações de outras pessoas que atuam no seu repositório.)

Realmente não importa; Eu acho que é estilo e preferência pessoal. Como escrever quase tudo, apenas seja consistente consigo mesmo e com outros comentários.

Os comentários do código devem ser naturais para leitura.

Se você estiver lendo o código dizendo a si mesmo "Este código está executando o X", escreva o comentário no tempo presente, pois é provável que alguém que esteja lendo o código naquele momento também esteja pensando. Se, por outro lado, você está pensando em um ponto específico "Este código fez X", então deve ser passado. No final, tudo se resume à preferência pessoal, a menos que, por algum motivo, você esteja sob as diretrizes de como comentar seu código (por exemplo, para um projeto de equipe ou para uma classe, etc.).

Se você estiver usando o git, a convenção é usar o tempo presente, porque as mensagens de confirmação geradas com as ferramentas git (por exemplo, mesclagem) usam o tempo presente.

Você deve usar o tempo passado.

A razão é que você está respondendo à pergunta: o que esse compromisso conseguiu? Pense nisso como dizer ao seu VCS o que você fez:

Confirmar 123
XYZ alterado para fazer ABC

Para dar exemplos contrários, usar o tempo futuro faz parecer que você está pedindo a alguém que faça isso:

Confirmar 123
Alteração XYZ para fazer ABC

e usar o tempo presente soa como se você estivesse na metade:

Confirme 123
Alterando XYZ para fazer ABC

Use o tempo presente: "Altere X para Y", quase como se fosse um item em uma lista TODO clara.

Em geral, assim como um roteiro, evite verbos como "ser" e "é". Por exemplo, não é "ele está andando", mas "ele está andando".

Mas neste exemplo em particular - se você está falando sobre comentários de código e não de check-in - acredito que "Alterar X para Y" é um comentário terrível. Ele não adiciona novas informações e, se o código for alterado, pode até estar incorreto. É melhor se você extrair o código em um método (ou classe) e depois documentar esse método. Se estiver claro o suficiente, apenas um bom nome de método será suficiente.

Falando nisso, para documentar métodos, você pode usar o tempo futuro, por exemplo: "Se o número fornecido for negativo, absretornará a magnitude do número".

Os comentários são (ou deveriam ser), como qualquer coisa escrita, expressões de algo, e eles devem simplesmente seguir as mesmas regras em idiomas naturais (levando em conta abreviações e abreviações específicas para a situação ou artefato que está sendo documentado.

Comentários sobre o tempo presente ( .ie "muda" ou "está mudando" ) indica que um dado que está sendo operado pelo algoritmo documentado está sendo afetado de alguma forma. Ou seja, indica o que o código está fazendo ou o que está ocorrendo nos dados que estão sendo manipulados.

Os comentários no tempo passado devem indicar uma afirmação, pré-condição ou pós-condição de algo que aconteceu antes do ponto em que o comentário reside. Por exemplo:

A entrada já foi validada antes de inserir este bloco de código

ou

Os dados foram gravados no arquivo no final deste código sendo executado

Os comentários no tempo passado também podem explicar por que algo está sendo feito ( essa função executa X e Y para lidar com um problema com o banco de dados herdado ) .

Comentários no passado, indicando uma alteração no próprio código (ou seja, X foi alterado para Y ), não devem existir no código. Em vez disso, eles devem existir como comentários de revisão no repositório de código-fonte.

Os comentários no futuro devem indicar uma condição que precisa ser atendida ou tratada, mas que, por X ou Y, o motivo não está sendo feito no momento. Por exemplo:

Quando finalmente migrarmos o banco de dados, teremos que mudar essa lógica

ou

TODO: o mais cedo possível, revisite a validação da entrada - pode falhar no tipo de entrada X ou Y, pode exigir mudanças maciças que não podem ser implementadas no momento.

Para os comentários posteriores do tipo TODO , alguma outra forma de documentação deve existir para garantir que essas alterações realmente ocorram. A última coisa que você quer são TODOs perdidos no tempo e no espaço: P

Leve-o com um pouco de sal, mas normalmente essas são as regras que eu costumo seguir quando faço meus próprios comentários.

Comentar é sobre se comunicar com seres humanos; portanto, embora a consistência seja importante, é importante não se prender aos princípios quando os próprios princípios atrapalham a boa comunicação. Dito isto, eu uso os seguintes pseudo-padrões:

• Os comentários que descrevem um comportamento desejado assumem a forma de uma sentença imperativa no tempo presente.

  // Calculate the width of the curve at x height.
  

• Use um conjunto de palavras-chave com letras maiúsculas para descrever temas comuns na codificação (e para facilitar a pesquisa):

  // NOTE: <This code was written this way for a reason.>
  // TODO: <This code is incomplete. Finish it.>
  // HACK: <This code was written this way for a reason that you won't like.>
  // FIXME: <This code has a known flaw. Fix it.>