Re: Deleting old references to ticket numbers and avoiding new ones
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 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 > Sent: Tuesday, March 30, 2021 2:24 PM > To: 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) >
Re: Deleting old references to ticket numbers and avoiding new ones
+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 Sent: Tuesday, March 30, 2021 2:24 PM To: 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)
Re: Deleting old references to ticket numbers and avoiding new ones
+1 I am pretty sure we had this discussion a long time ago and agreed to it. I can’t view the archives though since it appears markmail doesn’t like newer versions of Chrome or Safari. -Jake > On Mar 30, 2021, at 2:24 PM, Hale Bales wrote: > > 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)
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)
