Take the 2-minute tour ×
English Language & Usage Stack Exchange is a question and answer site for linguists, etymologists, and serious English language enthusiasts. It's 100% free, no registration required.

In software engineering we use version control systems. Every time we check in modifications we usually leave a message with a summary of change. The question for me has always been: what is the most appropriate and practical tense and form for these messages? Examples:

  1. Changed the function argument type to int

  2. Function argument type changed to int

  3. Function argument type is changed to int

  4. Function argument type has been changed to int

  5. Function argument type is now int

By "practical" I mean, because most messages are in the same form, they should be succinct, to the point, technical/formal. Best candidate in this regard is probably (2). Sometimes it is tempting to use (5) but you end up flooding your message log with "now", which is not nice. (4) is too long although looks (to me) appropriate in many cases. And finally, (1) and (3) feel wrong somehow, although (1) especially is a widely used one in programming, as far as I can tell.

Any thoughts, suggestions?

Edit: some other forms found by some googling:

  1. Change the function argument type to int

  2. Changing ...

  3. Changes ...

share|improve this question
    
This is a very technical questions. You might want to clarify what you are trying to document, first. And then come back here and check the tenses. E.g. do you want to document what a someone (a developer) did or do you want to document what changed? –  Alex Dec 10 '10 at 23:43
    
@Alex: I want to document very briefly what I've changed and am now checking in to the source repository. –  mojuba Dec 10 '10 at 23:52
    
#1 in your added examples is the most concise (extremely useful when integrating frequent changes in a large team) and grammatically answers the question "What does this commit do?", which is why I believe my answer is best. –  David Rivers Nov 28 '11 at 9:31
    

5 Answers 5

up vote 10 down vote accepted

Since presumably (1) you're checking in something that you did, and (2) the change has already happened (otherwise you'd have nothing to check in), I'd go with the simple past:

Changed function argument type to int.

If you're checking in a change on behalf of a team, I could also see using:

Function argument type changed to int.

The simple past is the least wordy tense — no helping verbs, no "now"— and is generally the easiest to understand.

I wouldn't suggest using a continuous present or future tense such as "changing", because then the log becomes unclear about what was changed when. (Akin to the problem of distances in driving directions: when it says "left turn — 5 miles", does that mean the left turn is 5 miles ahead, or do I make a left turn now and then go 5 miles until the next step?)

share|improve this answer
4  
One other advantage of (2), “Function argument type changed to int”, is that it puts the more important part first — always a stylistic virtue. Scanning down a long list of such messages will be slightly easier and quicker with this form, I would imagine. –  PLL Jan 15 '11 at 6:04

I think it is up to preference. Personally, I like using imperative: "Change the function argument to int." This especially makes sense if you are using a task management system with task numbers: "Task ID#: 5719 Change the function argument to int." (Or defect numbers, or what have you.) From context you can infer that the task has been completed regardless of verb tense. To indicate partially completed tasks, you can add qualifications such as "Change the function argument to int (partial)" or "Change the function argument to int - 50% complete" or whatever makes sense in your situation.

But definitely check with your colleagues on accepted conventions, unless you're the boss and can tell them what to do. :)

share|improve this answer
    
The latter... :) Psychologically I'm more comfortable with the past tense because it indicates an accomplishment. Present tense in a way reminds of the neverending flow of task items :) –  mojuba Dec 11 '10 at 1:01
2  
Hehe, that is understandable. I probably should have mentioned that I find the ability to copy and paste the task name convenient, and also I get a sense that using the simplest verb form is "clean"; thus, using imperatives psychologically supports my lazy and OCD tendencies. :D –  Mitch Schwartz Dec 11 '10 at 1:42

I think we should differentiate between centralized version control systems, wherein commits are only linear, and decentralized ones.

Assuming a decentralized VCS

To someone reading a log of comments, each commit begs the question: "What do I change by using this commit?". This is especially true in a scenario wherein one is cherry-picking a changeset from one branch into another. Also, consider if one fetches commits from a remote repository and wants to inspect them first. With this audience in mind, the imperative mood in present tense makes most sense. E.g.:

[Use this commit to] Refactor the User model.

Since this is normally the only context in which I am reading VCS comments, I prefer this style of writing them.

The past tense just seems superfluous to me. Of course each revision has already occurred (in the past), or it would not have been committed yet! The temporal context is unnecessary.

Assuming a centralized VCS

In this situation I can see the logic in using the simple past tense, as changes are made completely linearly. However, I think the tense of commit messages becomes a stylistic concern (since the past tense is still assumed). I believe that the current tense, imperative mood scans better (no superfluous "d"s or "ed"s in verbs), but that may simply be a personal preference.


Anyway, I do agree with CJM: I think that consistency is more important than grammar or style points.

share|improve this answer

In my experience, it doesn't matter how you phrase it, as long as you remain consistent. Clearly, you are recording what actions have happened, so past tense is appropriate.

Speak to your colleagues, and agree on a common approach.

share|improve this answer

In revision comments, as in any programming comments, the "why" if often more important than the "what," so please permit me to reformulate a bit. If you focus on the action, you might have:

  • fixed bug 1234
  • fixing bug 1234

But I suggest you focus on the result:

  • fixes bug 1234
  • fix for bug 1234

As @Alex said in a comment, you first have to decide what you're trying to say. If you're trying to describe the change (thinking of the change as a noun, an entity that the version control system can tell you about) then you want a phrase that characterizes the change itself. For example, if the change was motivated by dissatisfaction that the system limits the user to a single "fooblatz" then the comment might be "allow use of multiple fooblatzes," not "changed data structure to reflect revised fooblatz cardinality."

share|improve this answer

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.