3 ms·

Spent 5 minutes trying to figure out where field_name is in the second list... I thought it was the same commits rewritten to be more scannable, but they are fr

by andai 3y ago

Spent 5 minutes trying to figure out where field_name is in the second list... I thought it was the same commits rewritten to be more scannable, but they are from a different project. (I scanned, naturally, the article itself!) Or more generally, I thought the point of the article would be that the function / variable names from the first list would be moved to the beginning of sentences. But in the 2nd example they are completely absent, favoring much vaguer / high level descriptions. So we are unable to see the before/after effect for the same list of commits, I think most of the potential impact of the author's intended point is lost. (Also, the first half extolls the virtues of being able to read quickly, while the second half tells you to use longer sentences for everything for apparently no reason?)

hmeh 3y ago
Author here. I chose two real sets of commit messages rather than to fabricate one. Fabricating one may have made the second list easier to scan -- you'd already know what you were looking for and you would have some familiarity with the content. In any case, it's certainly not a perfect experiment or demonstration. The specific function/variable names do not often make appearances in our commit messages (though they do sometimes, as do class names). They do, however, make very clear appearances in diffs. Commit messages stand on their own for their own purpose -- it's an index, and indexes are for scanning. If you need to read further, you zoom in. Also, I wasn't trying to say to "use longer sentences for everything," where did you get that from? I offered some specific clarifications on how we write some common commit messages, and they may be longer than some alternatives, but our reasons are for clarity and consistency. We don't mind slightly longer commit messages, in large part because the first few words tend to be the most important.

by andai 3y ago

hmeh 3y ago

Author here. I chose two real sets of commit messages rather than to fabricate one. Fabricating one may have made the second list easier to scan -- you'd already know what you were looking for and you would have some familiarity with the content. In any case, it's certainly not a perfect experiment or demonstration. The specific function/variable names do not often make appearances in our commit messages (though they do sometimes, as do class names). They do, however, make very clear appearances in diffs. Commit messages stand on their own for their own purpose -- it's an index, and indexes are for scanning. If you need to read further, you zoom in. Also, I wasn't trying to say to "use longer sentences for everything," where did you get that from? I offered some specific clarifications on how we write some common commit messages, and they may be longer than some alternatives, but our reasons are for clarity and consistency. We don't mind slightly longer commit messages, in large part because the first few words tend to be the most important.