From: Kaartic Sivaraam Date: Wed, 13 Sep 2017 06:44:40 GMT Subject: Re: [PATCH 10/10] add UNLEAK annotation for reducing leak false positives Message-ID: <26c0badc-0443-fca0-a12b-033a87dcffb1@gmail.com> In-Reply-To: <20170912152935.iqmj6jpkvgifaju2@sigill.intra.peff.net> On Tuesday 12 September 2017 08:59 PM, Jeff King wrote: > Like all good writing rules, I think it's important to know when to > break them. :) That's right. "Have guidelines but 'Be bold' enough to break them when they seem to be inducing counter productivity." > Writing in the imperative is _most_ important in the subject. You're > likely to see a lot of subjects in a list, and it makes the list easier > to read if they all match. It also tends to be shorter, which is good > for subjects. > > For short commit messages, I think the imperative also keeps things > tight and to the point: describe the problem and then say how to fix it. > The recent 0db3dc75f is a good example (which I picked by skimming > recent "git log" output). But saying "this patch" is IMHO not that big a > problem there, as long as it isn't done excessively. > > When you the explanation is longer or more complicated, the imperative > can actually be a bit _too_ terse. In longer text it helps to guide > readers in the direction you want their thoughts to take. Having a > three-paragraph explanation of the problem or current state of things > and then jumping right into "Do this. Do that." lacks context. A marker > like "this patch" helps the reader know that you're switching gears to > talking about the solution. > > I also think that "I" is useful in avoiding the passive voice. It can > certainly be used gratuitously and make things less clear, but in most > cases I'd rather see something like "I tested performance under these > conditions" than "Performance was tested under these conditions". I also > often use the "academic we" here even when I worked on something myself. Thanks for taking the time to give the detailed and clear explanation. --- Kaartic