[buckminster-dev] Re: Check-in comments

[Achim Demelt <a.demelt@xxxxxxxxxxxxx>]

+1

I've been using this kind of comment policy successfully in my own projects 
for quite some time now. Browsing SVN history will then very easily point 
you to the rationale behind this or that change others (or even you) made 
months or years ago.

In a similar vein, I'd like to ask what others think about mentioning the 
bugzilla number in inline code comments, too. That's not always appropriate, 
of course. A huge new feature: no. A seemingly inconspicuous "if"-statement 
to prevent a MysteriousMoonPhaseException later on, as reported by a user 
from Alpha Centauri: yes.

Personally, I like the fact that I can simply CTRL-click the number and 
Mylyn (if configured) opens the appropriate issue. Even without Mylyn, I 
think the indication of _why_ a certain piece of code looks the way it is 
helps other people understand the code base.

Cheers,
 Achim

Thomas Hallgren wrote:

> Hi,
> I would like us to unify our check-in comments. I know that many projects
> use comments similar to this one:
> 
>    Bug 283104 - Qualifier replacement disabled when keyword 'qualifier' is
>    prefixed
> 
> i.e. the relevant bugzilla number and its heading. I've been using this
> style too lately. This comment style makes it very easy to create list of
> what's changed since the last release and it's also very easy to bring up
> information about the actual bug, should the need arise. Entering the full
> URL clobbers the real information IMO and everyone knows where to find the
> bugzilla anyway.
> 
> Moving forward, I'd like all our check-ins to have a comment like this
> unless the change is so trivial that no bugzilla was ever entered.
> 
> What do others think about this idea?
> 
> Regards,
> Thomas Hallgren