Once in a while, I leave comments like
# We only need to use the following for V4 of the computation. # See APIPROJ-14 for details.
# We only need to use the following for V4 of the computation. # See https://theboringcompany.atlassian.net/browse/DIGIT-827 for details.
My main concern with doing so is that it increases our dependence on JIRA, so those comments would be entirely moot if we were to migrate into another project management system. While I don't foresee that happening in the near future, I remain wary of the increased coupling of organizational components (in this case: code, code repositories and a project management system).
However, I do see the benefit of having references to documented design decisions and feature inspiration throughout the code base. As far as I can tell, the benefits are
- a clear path to design decisions, which helps with debugging and ramping up on particular segments of unfamiliar code,
- fewer multi-line comments, which makes code seem cleaner/less intimidating to new contributors,
- a clear path to (potentially) current technical and non-technical stakeholders, and
- a decrease in the number of "why is this here" questions because of the aforementioned.