Details
-
Type:
RFC
-
Status: Implemented
-
Resolution: Done
-
Component/s: DM
-
Labels:
Description
While working on DM-7892 I noticed that the old Doxygen guidelines on Confluence recommended the use of the @todo tag to flag unfinished code. This tag's output is collated on a moderately-well-hidden Doxygen page. (Curiously, the related tag @bug is not used anywhere.)
Given that we have an actual bug tracker, that lists of unresolved issues arguably do not belong in API documentation, and that I'm not sure the @todo list is actually read by anybody, I would like to avoid transferring rules regarding @todo from Confluence to http://developer.lsst.io, effectively removing them from the C++ style guide. John Swinbank suggested I RFC this change to see if anybody objects.
As an alternative to merely not mentioning @todo, we could make a stronger rule to the effect that the @todo tag should not be used, and that unfinished work should instead have a Jira ticket.
Attachments
Issue Links
Activity
Yes, my opinions match what Jim Bosch and John Parejko are saying.
I don't intent to continue aggregating Doxygen todos in https://pipelines.lsst.io. And I agree that todos should not be written in Doxygen comments (or docstrings on the Python side) as it creates an unmanageable expectation that we're reporting all possible API/implementation development through our API reference documentation. So I'd say we disallow @todo outright. Thanks for RFCing this Krzysztof Findeisen.
And expanding on what John Parejko is saying, maybe a useful outcome of this RFC is that we add some text to the DM C++ and Python Style Guide's comment formatting sections recommending that TODO comments we allow to be merged to master always mention a ticket. We don't say that in https://developer.lsst.io/coding/python_style_guide.html#comments or https://developer.lsst.io/coding/cpp_style_guide.html#comments.
Robert Lupton, given Jonathan Sick's reply above, would you be willing to give up @todo so long as other forms of to-do comments were still allowed, and were required to refer to a Jira ticket?
Krzysztof Findeisen
added a comment - Robert Lupton , given Jonathan Sick 's reply above, would you be willing to give up @todo so long as other forms of to-do comments were still allowed, and were required to refer to a Jira ticket? It sounds like not mentioning @todo, and adding a style rule that links TODOs to Jira (see below) is broadly acceptable to most people. If I don't hear any objections by 12:00 PDT/3:00 EDT tomorrow, I will mark this ticket as adopted.
Proposed rule text in Python style guides (C++ text would be analogous):
To-do comments SHOULD include a Jira issue key
If the commented code is a workaround for a known issue, this rule makes it easier to find and remove the workaround once the issue has been resolved. If the commented code itself is the problem, this rule ensures the issue will be reported on Jira, making it more likely to be fixed in a timely manner.
# TODO: DM-12345 is triggered by this line
|
# TODO: workaround for DM-6789
|
Krzysztof Findeisen
added a comment - - edited It sounds like not mentioning @todo , and adding a style rule that links TODOs to Jira (see below) is broadly acceptable to most people. If I don't hear any objections by 12:00 PDT/3:00 EDT tomorrow, I will mark this ticket as adopted.
Proposed rule text in Python style guides (C++ text would be analogous):
To-do comments SHOULD include a Jira issue key
If the commented code is a workaround for a known issue, this rule makes it easier to find and remove the workaround once the issue has been resolved. If the commented code itself is the problem, this rule ensures the issue will be reported on Jira, making it more likely to be fixed in a timely manner.
# TODO: DM-12345 is triggered by this line
# TODO: workaround for DM-6789
Adopting as summarized in the previous comment.
Krzysztof Findeisen
added a comment - Adopting as summarized in the previous comment. 
What Jim Bosch said above: todo's are useful in comments as a marker for the location of the problem (with the relevant Jira ticket linked). Line numbers in Jira tickets can bit rot quite quickly, so having a direct // TODO:
DM-12345is triggered by this line is very handy. I'm not sure of their utility in the actual documentation, so I'm mostly in favor of this, and possibly even the stronger version.