Comentários de controle de versão - tempo passado ou presente [fechado]

12

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.
Robert W
fonte
27
Você não quer dizer "controle de versão verificando comentários"? Eu nunca adiciono comentários documentando alterações no código real. Isso é confuso.
31411 JohnFx
1
Estou realmente confuso - se @JohnFx estiver correto, então esta é uma questão completamente diferente. Pessoalmente, não vejo por que @Robert não poderia ter significado comentários no código fonte.
Armand
FYI: Eu quis dizer check-in, não "check"
JohnFx 08/03/11
Desculpe - apenas para esclarecer a confusão, eu quis dizer comentários sobre controle de versão, em vez de comentários no código-fonte. A pergunta foi atualizada.
Robert W

Respostas:

19

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
    ....
}
Armand
fonte
NB: acho que todos os comentários no código acima são supérfluos, mas não necessariamente estariam em um exemplo não trivial.
Armand
7
Agora que a pergunta mudou, esta resposta está um pouco fora do tópico.
Armand
22

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.

Tim
fonte
10

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.).

Berin Loritsch
fonte
3
+1, embora eu ache que os comentários sobre controle de versão também estejam no passado. :-)
Eric King
Não é tão ruim ter um arquivo de registro de alterações separado; colocar em quarentena os comentários de confirmação não prejudicará muito, mas pulverizá-los por todos os arquivos é apenas um ruído doloroso.
Donal Fellows
Commit meesages pode ir de qualquer maneira. Costumo olhar para ele, pois essa foi a ação atual pelo motivo do commit naquele momento. No final do dia, esta é uma área em inglês que provavelmente não é problema em dividir os cabelos. Não é como "come, tiros e folhas" en.wikipedia.org/wiki/Eats,_Shoots_%26_Leaves
Berin Loritsch
10

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.)

mipadi
fonte
1
Concordo que parece estranho no começo, e vê-lo como um patch é definitivamente o caminho certo a seguir. Uma coisa que tenho feito é recitar "Este patch será" na minha cabeça antes de ler minha mensagem de confirmação. É uma mudança de se perguntar "O que eu fiz neste patch?" (Corrigido o erro de segmentação) para se perguntar "O que esse patch fará?" (Corrija o erro de segmentação).
Nick Knowlson
5

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.

G__
fonte
2

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.).

Kenneth
fonte
1

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.


fonte
1

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

Garry Shutler
fonte
0

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".

Macneil
fonte
0

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.

luis.espinal
fonte
0

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.>
    
kojiro
fonte