Many good questions generate some degree of opinion based on expert experience, but answers to this question will tend to be almost entirely based on opinions, rather than facts, references, or specific expertise.
If this question can be reworded to fit the rules in the help center, please edit the question.

27

Don't you mean "version control checking comments"? I never add comments documenting changes in the actual code. It clutters it up.
–
JohnFxMar 8 '11 at 17:46

1

I'm really confused - if @JohnFx is correct, then this is a completely different question. I personally don't see why @Robert couldn't have meant comments in source code.
–
AlisonMar 8 '11 at 19:25

uses the imperative, present tense: "change", not "changed" or "changes".

It may seem a bit odd at first, but if you think of a commit as a patch that does something, it makes more sense. (This is especially true in a DVCS like Git, where you pull changesets from other people that act on your repo.)

I agree that it does seem odd at first, and viewing it as a patch is definitely the right way to go. One thing I've been doing is recite "This patch will " in my head before reading out my commit message. It's a switch from asking yourself "What did I do in this patch?" (Fixed threading bug) to asking yourself "What will this patch do?" (Fix threading bug).
–
Nick KnowlsonMar 10 '11 at 19:11

Commenting is about communicating to human beings, so while consistency is important, it's important not to get bogged down in principles when the principles themselves get in the way of good communication. That said, I use the following pseudo-standards:

Comments describing a desired behavior take the form of a present-tense imperative sentence.

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

Use a set of all-caps keywords to describe common themes in coding (and to make it easy to search for):

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

Comments are (or should be), like anything written, expressions of something, and they should simply follow the same rules in natural languages (taking into account shorthands and abbreviations specific to the situation or artifact being documented.

Comments on the present tense (.ie "it changes" or "it is changing") indicates that an piece of data being operated by the documented algorithm is being affected somehow. That is, it indicates what the code is doing or what is occurring to the the data being manipulated.

Comments in the past tense should indicate an assertion, precondition or post-condition of something that has happened prior to the point where the comment resides. For example:

Input has already been validated before entering this block of code

or

Data has been written to file at the end of this code being executed

Comments in the past tense can also explain why something is being done (this function does X and Y to deal with a problem with the legacy database.)

Comments in the past tense indicating a change to the code itself (.ie. X was changed to Y) should not exist in the code. They should instead exist as revision comments in the source code repository.

Comments in the future should indicate a condition that needs to be met or addressed, but that for X or Y reason is not being done right now. For example:

Use the present tense: "Change X to Y," almost as if it were an item on a clear TODO list.

In general, just like a screenplay, avoid verbs like "to be" and "is". For example, it's not "he is walking," but "he walks."

But in this particular example-- if you're talking about code comments, and not check-in comments-- I believe "Change X to Y" is a terrible comment. It adds no new information, and if the code were to change it might even be incorrect. It's better if you extract the code into a method (or a class) and then document that method instead. If it's clear enough then just a good method name will be sufficient.

Speaking of which, for documenting methods, you could use the future tense, e.g.: "If the number provided is negative, abs will return the magnitude of the number."

If you're reading the code saying to yourself "This code is doing X" then you should write the comment in present tense as this is likely how someone reading the code at that time will be thinking as well. If on the other had you're thinking at a particular point "This code did X" then it should be past tense. In the end it comes down to personal preference unless for some reason you're under guidelines of how to comment your code (ie for a team project or for a class, etc).

Comments are static things, so they should present the state of the program as is, and not as it is going to be. To answer your specific question, it would be more appropriate to use past tense.

However, this type of comment is better suited to your version control system. Version control does a much better job of change tracking than manual comments. With Version control systems, it is more appropriate to document in present tense as those comments apply at the moment the change is committed. But, either will work.

I would highly recommend that the only comments in your code should be what is required to understand the code itself--the purpose, business logic, and exceptional cases. Leave change set documentation to your version control system. If you aren't using a VCS, start now. There are several high quality VCS that are free (Subversion, Mercurial, Git, etc.).

+1, although I think version control comments should be in past tense, too. :-)
–
Eric KingMar 8 '11 at 17:55

It's not too bad to have a separate changelog file; quarantining the commit comments to there will not hurt too much, but spraying them all over every file is just painful noise.
–
Donal FellowsMar 9 '11 at 11:29

Commit meesages can go either way. I tend to look at it as that was the present action for the reason of the commit at that time. At the end of the day, this is an area of English that it's probably OK not to split hairs. It's not like "Eats, Shoots and Leaves" en.wikipedia.org/wiki/Eats,_Shoots_%26_Leaves
–
Berin LoritschMar 9 '11 at 13:10