You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@trafficserver.apache.org by John Plevyak <jp...@acm.org> on 2010/03/26 19:27:00 UTC

Names/Bug# in comments and consistency

There are a number of places in the code where
folks have made a change and surrounded the change
with comments with their name and perhaps some bug
number.

I was wondering what folks think of this?  I think
it makes the code look messy and unprofessional, as
if it is some historical artifact being tinkered around
with by folks who don't really feel like it is theirs.

It also seems to be an excuse to ignore the surrounding
coding and naming conventions and to generally treat
the change a patch (in the sense of a something glued on)
rather than a modification which results in a new (better)
product.

I don't mind if the bug is very obscure and there is
a comment block which describes a non-obvious aspect
of the implementation the lack of understanding of which
triggered the bug.  In other words if the bug # is just
an aside to a descriptive comment block.


Thoughts?

john



Re: Names/Bug# in comments and consistency

Posted by Bryan Call <bc...@yahoo-inc.com>.
I agree and in general it looks messy as if someone is marking their 
territory.  The exceptions I would think would be:

1. Temporary code that will soon be cleaned up and the comments 
removed.  This includes sort term hacks that have a short lifespan (less 
then 1 release). (I have done this)
2. If the code/bug fix is complex and takes a huge amount of comments 
and an email thread to understand its meaning.  This should be very rare 
and the code should be looked at to make it simpler.  This should only 
have a bug number and not their name.

-Bryan

On 03/26/2010 11:27 AM, John Plevyak wrote:
> There are a number of places in the code where
> folks have made a change and surrounded the change
> with comments with their name and perhaps some bug
> number.
>
> I was wondering what folks think of this?  I think
> it makes the code look messy and unprofessional, as
> if it is some historical artifact being tinkered around
> with by folks who don't really feel like it is theirs.
>
> It also seems to be an excuse to ignore the surrounding
> coding and naming conventions and to generally treat
> the change a patch (in the sense of a something glued on)
> rather than a modification which results in a new (better)
> product.
>
> I don't mind if the bug is very obscure and there is
> a comment block which describes a non-obvious aspect
> of the implementation the lack of understanding of which
> triggered the bug.  In other words if the bug # is just
> an aside to a descriptive comment block.
>
>
> Thoughts?
>
> john
>
>
>    



Re: Names/Bug# in comments and consistency

Posted by Leif Hedstrom <zw...@apache.org>.
On 03/26/2010 12:27 PM, John Plevyak wrote:
>
>
> I don't mind if the bug is very obscure and there is
> a comment block which describes a non-obvious aspect
> of the implementation the lack of understanding of which
> triggered the bug.  In other words if the bug # is just
> an aside to a descriptive comment block.
>    

I think at a minimum we should eliminate all non-Jira bug number 
references and comments. They are completely pointless, we have no way 
of finding that information.

For the rest, I agree that we shouldn't litter the code with such 
comments. In fact, I don't even know if it's useful to have any Jira bug 
references in the code at all. Since we require that all commits are 
associated with a Jira ticket (I hope everyone is on board with that 
still), it's pretty easy to use "svn blame" for example to get a 
reference from the code to which Jira ticket is associated with that 
commit. That should be enough as a cross reference IMO.

In the future, a useful tool could be to augment "svn blame" to also 
find the associated Jira ticket # :-).

So, in conclusion, my +1 would be to eliminate all "bug # comments" from 
the code entirely, with the caveat that we continue to require a Jira 
ticket with every commit (and as mentioned before, it's OK to use the 
one ticket for multiple commits).

Cheers,

-- leif