13

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

11

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

  • 5
    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
9

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

  • 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
  • 3
    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
7

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

Assuming a decentralized VCS with a non-linear history

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 with a linear history

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.

2

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.

0

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

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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