Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

For version control comments what do other users do/recommend - past or present tense?

I.e.

  • Changed x to be y.
  • or
  • Changing x to be y.
share|improve this question
27  
Don't you mean "version control checking comments"? I never add comments documenting changes in the actual code. It clutters it up. –  JohnFx Mar 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. –  Alison Mar 8 '11 at 19:25
    
FYI: I meant Check-in, not "checking" –  JohnFx Mar 8 '11 at 20:03
    
Sorry - just to clear up the confusion I did mean version control comments rather comments in the source code. The question has been updated. –  Robert W Mar 9 '11 at 9:36
add comment

11 Answers

up vote 18 down vote accepted

Comments should be read in context, so:

Present

For source comments above a method, or before some behaviour occurs:

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

Past

For source comments after some behaviour occurred

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

And for commit messages

function X changed


Mixed example:

// This function does X
function doX() {
    widget.doY()
    // did Y to widget to prepare it for Z
    ....
}
share|improve this answer
    
N.B. I think all the comments in the above code are superfluous, but they wouldn't necessarily be in a non-trivial example. –  Alison Mar 8 '11 at 17:56
4  
Now the question has changed, this answer is slightly off-topic. –  Alison Mar 9 '11 at 11:49
add comment

Past - Since anyone who reads it in the future will refer to the act of the change as have happened in the past.

Wording something as "Changing" implies that you are currently in the process of making the change and that the code may not be finished.

note: Personally, I only put in change comments when a drastic change has occurred.

share|improve this answer
add comment

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

share|improve this answer
3  
+1, although I think version control comments should be in past tense, too. :-) –  Eric King Mar 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 Fellows Mar 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 Loritsch Mar 9 '11 at 13:10
add comment

It doesn't really matter; I think it's personal style and preference. As per writing almost anything, just be consistent with yourself and with other comments.

share|improve this answer
add comment

Code comments should be natural to read.

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

share|improve this answer
add comment

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

share|improve this answer
add comment

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:

When we finally migrate the db, we will have to change this logic

or

TODO: asap, revisit validation of input - it might fail for X or Y type of input, might require massive changes that cannot be implemented right now.

For the later TODO type of comments, some other form of documentation should exist to make sure that such changes actually take place. The last thing you want are TODOs lost in time and space :P

Take it with a grain of salt, but typically those are the rules I usually follow when I do my own comments.

share|improve this answer
add comment

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.>
    
share|improve this answer
add comment

If you're using git the convention is to use present tense because commit messages generated with the git tools (e.g. merge) use present tense.

share|improve this answer
add comment

I use the imperative present tense, so something like:

Change "x" to be "y"

This is recommended by the Git developers:

  • the body should provide a meaningful commit message, which:
    • 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.)

share|improve this answer
1  
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 Knowlson Mar 10 '11 at 19:11
add comment

You should use the past tense.

The reason being you are answering the question what did this commit achieve? Think of it as telling your VCS what you did:

Commit 123
Changed XYZ to do ABC

To give counter examples, using the future tense makes it sound like you're asking someone else to do it:

Commit 123
Change XYZ to do ABC

and using the present tense sounds like you're halfway through it:

Commit 123
Changing XYZ to do ABC

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.