I STRONGLY AGREE with avoiding Jira ticket numbers in code comments. In an open-source system, code comments function as user-visible documentation (whether or not they're flagged for inclusion in the Javadocs), so rather than resorting to a ticket number in place of an explanation, provide the explanation. Thanks Hale!
On Tue, Mar 30, 2021 at 4:16 PM Donal Evans <doev...@vmware.com> wrote: > +1 > > In theory, every commit is now associated with a GEODE jira ticket, so > leaving a comment in the code when putting in a fix saying that it's for > that ticket is redundant. Good commit names and messages would provide the > broader context for changes, and regular comments that don't refer to a > ticket at all can provide the fine-detail explanation that's sometimes > needed to clarify code. > ________________________________ > From: Hale Bales <hba...@vmware.com> > Sent: Tuesday, March 30, 2021 2:24 PM > To: dev@geode.apache.org <dev@geode.apache.org> > Subject: Deleting old references to ticket numbers and avoiding new ones > > Hi all, > > I have noticed in the past that there are a lot of ticket numbers in the > code (along the lines of "fixes #") that reference tickets in a system that > very few people still have access to. Since the average Geode developer > does not have access to this system, having these in the code does not > provide any value. I would like to propose that we remove all references to > old ticket numbers when we come across them. If you happen to be one of the > few people with access to this information, you could potentially remove > the reference to the ticket number and add a note about the contents of > that ticket. Finally, I would like to propose that we work to avoid this > issue in the future (in case we every stop using Jira) by avoiding having > just the Jira ticket number in a comment. Instead, we should provide both > the ticket number and a short description of that ticket so that we can get > all the necessary information from the comment. > > ~hale (they/them) >
