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