word choice - Version control messages: what tense?


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





Answer



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


Comments

Post a Comment

Popular posts from this blog

verbs - "Baby is creeping" vs. "baby is crawling" in AmE

Years and years ago, I remember reading in a book on AmE usage that the phrasal turn a baby creeps before it walks was to some extent more common to AmE than to BrE, which preferred exclusively the "crawl" version. And so, I just recently checked on the accuracy of that information on NGram Viewer , and it actually was fact... more than a century ago! What I would like you to tell is if it would sound sort of weird to hear someone say today in the US that a child "creeps" before walking and running (see Synonyms ) rather than it crawls. Also, what's the story to those terms? How did "to crawl" come to prevail and supersede "to creep" to describe the way a baby moves around? As with a plant, so with a child. His mind grows by natural stages. A child creeps before he walks , sits before he stands, cries before he laughs, babbles before he talks, draws a circle before he draws a square, lies before he tells the truth, and is selfish before he
Read more

commas - Does this sentence have too many subjunctives?

Does this sentence have too many subjunctives? If it please the king, let it be decreed that they be destroyed, and I will pay 10,000 talents of silver into the hands of those who have charge of the king's business, that they may put it into the king's treasuries. I am stumped by this sentence construction. First, there is "Let it be," which is a common English idiomatic phrase, but then it follows another subjunctive. Is that to say you can actually have a subjunctive followed by another subjunctive? Also, why does the sentence use "please"? If that's the subjunctive tense there, then why is it followed by another subjunctive instead of a conditional, or maybe "Let it be" is the conditional? Lastly, I wish to know how the that is used in the sentence. Perhaps, the simplified sentence can be restated like so: Let it be decreed that they be destroyed and that they may put it into the king's treasuries. If not, maybe the simplified sent
Read more

grammatical number - Use of lone apostrophe for plural?

I've been reading William Manchester's book "American Caesar", which is about Douglas MacArthur, and I found that he uses a strange convention for pluralizing the family name. When talking about the MacArthurs as a whole, he writes MacArthur' with an apostrophe, as in "After the war, the MacArthur' lived in Tokyo while the general was proconsul" (yes, he uses that term to describe him). I have never seen or heard of a rule that would prescribe this. Manchester is a bit old-timey in his style: for example, he also writes "in behalf of" instead of "on behalf of", which is the only one I have ever seen. So perhaps this is similar. Where does he get this apostrophe from? Edit: There seems to be some difficulty finding examples, which is odd. Here is a direct link to a page from Google Books that shows the apostrophe.
Read more

etymology - Where does the phrase "doctored" originate?

This is a phrase I’m particularly confused about, because it’s used often when something is manipulated or changed. For example, sometimes images surface online that are clearly Photoshopped, but people refer to them as “doctored” images. Why use the word “doctored” here? Answer The earliest Google Books match for an instance of doctored in a transitional (or perhaps post-transitional) sense between "amended" and "adulterated" appears in William Marshall, The Rural Economy of Glocestershire; Including Its Dairy: Together with the Dairy Management of North Wiltshire, and the Management of Orchards and Fruit Liquor, in Herefordshire , volume 2 (1789): Men in general, however, whose palates are set to rough cider, consider the common sweet sort as an effeminate beverage; and rough cider, properly manufactured, is probably the most generous liquor; being deemed more wholesome, to habits in general, than sweet cider:—even when genuine. That which is drank, in the kingd
Read more

phrases - Somebody is gonna kiss the donkey

I heard this phrase when I was watching Battleship. An old man said, "Somebody is gonna kiss the donkey." I do not know what it means, I only heard it in a movie. What is this phrase mean? In Addition: I think it was Rihanna who said "Saddle Ridge will be in weapons range in five minutes," then the old man stated the phrase. Answer It is a confused attempt at a play on (for example) "kiss my ass," or, some similar phrase. It is quite common in English today that idioms get mangled.
Read more

typography - When a dagger is used to indicate a note, must it come after an asterisk?

The typographical symbol dagger (†) has several meanings. Possibly its most common use is as a footnote marker. According to You Have a Point There: A Guide to Punctuation and Its Allies ( Partridge , 1953), when it is used for this purpose, it must be used for second footnotes only; the first footnote should be indicated by an asterisk (*), the third a double dagger (‡) and further footnotes other symbols or numbers. Where does Patridge's rule fall on a scale of one to ten, where one is "this is just one guy's random opinion" and ten is "this is a widely accepted rule of English and any deviation from it is unarguably incorrect"? This question was inspired by this Meta Stack Overflow question about the use of daggers on Stack Exchange site FAQ pages . Answer The dagger (also known as an obelisk ) is properly used for the second footnote. The asterisk is for the first, and the double dagger is for the third. This is supported by several websites: And so
Read more

etymology - Origin of "s--t eating grin"

What is the origin of the phrase shit eating grin ? How did it come to mean showing smugness or self-satisfaction of an individual's actions? Answer From the Urban Dictionary: ...these uses are documented in the Oxford English Dictionary no earlier than 1957 There have been similar expressions used quite far back: In Book XXI of his History of Rome, Livy describes a Carthaginian sect of coprophages, the risus faecivorus, or shit-eating grin, being commonly displayed by its adherents. Although, its origin is undetermined, they may have been incidents which caused the invention of this phrase. Below is an excerpt: "1944 Jrnl. Nerv. & Mental Dis. XCIX. 959 Among demented patients in advanced stages of their illness,..it is not rare to see some of them grasp their own feces, chew them and eat them often with great pleasure and satisfaction (coprophagia).
Read more