Software Design/Link to a ticket from an unusual place in code
Checklist questions:
- Does a hack or workaround code for some bug has a comment including a link to the ticket describing this bug?
- Does a TODO comment link to the ticket tracking the corresponding task?
- Does temporary code have a comment with a link to a ticket or a relevant discussion where this code was justified if there is any?
- Is puzzling code (either due to unclear purpose or obscure semantics prepended with a comment with a link to a ticket or other resource providing some context or explanation if there is any?
Why
[edit | edit source]Readers of unusually looking or bewildering code are more likely to want to obtain additional context. Extracting the context through browsing the editing history of the file through the VCS and finding to which pull request the relevant commit belongs is time-consuming, making the code harder to learn.
As URLs are quickly recognizable in the normal code, they catch the attention of code readers and developers who may have navigated to the code with a goal in mind unrelated to the subject unusual code. This may prompt them to check whether the subject hack, fixme, or temporary code is now eligible to be fixed, e. g. if the blocker bug in an upstream library has been fixed. Additionally, if too many such pieces of code with corresponding links accrue in the code for a class or a subsystem, this may become visually recognizable to people whenever they visit the code for the system. This would be a reminder for them to take time to fix some of these places with hacky code. These two effects may help the developers to keep the technical debt in control without requiring their explicit efforts (deliberate planning or tracking of these problems in code), and with less cognitive load.
Why not
[edit | edit source]Links in comments catch the attention of the readers and thus making them to expend more mental efforts to keep the focus on their task at hand.
When the context of the issue is small so it can fit a comment spanning one or a few lines of code or could be summarized to this size, inserting a link instead of a plain text comment providing the context is an indirection which itself makes the semantics or the purpose of the unusual code less apparent due to the indirection and that the text describing the context and the code not directly adjacent. However, if providing the context would be a long comment and there are several places in the codebase where it is needed, putting such comments instead of just a link creates duplication and increases the total code size.
Linking to relevant tickets from normal business logic code (for example, a documentation comment for an ordinary class linking to the ticket in the context of which the class was added to the system) may be taking this practice too far in the first place because this may unnecessarily catch code readers' attention at too many places and be a poor substitute for writing proper documentation and comments.