Approaches for comment duplication

Question

For code, we know approaches like DRY and we tend to extract common functionality. What approaches are recommended for comments? Perhaps it's a really open question, so I'm going to go with my specific scenario:

In a project I work for, we use a library for charts, which has a few bugs. It's not very well maintained and it's difficult to change that in the near future.

I have like 8/9 files with different implementations of different charts which use this library, and today I found my self having to implement a complex workaround for each of them due to a bug in the library. Because of that, I thought of a four-or-five-line comment clarifying why is that workaround required (like the scenario that caused it and why that fix is correct)

Even though the root cause of the bug is the same, the solutions are different for each file (for each chart), so I cannot extract the solution into a common code. So I found myself having to copy the exact same comment into every file, which increases the chances of, at some point, becoming stale or out of date at some point in the future.

What approaches do you consider for repeated comments across different files? Perhaps for this particular scenario, it might make sense to create a small markdown file with the comment and link it instead of having the same comment in 7/8 locations, but I wonder if it's worth the effort when it is just 3 or 4 files. Or maybe there are other approaches for comment management.

Answer 1

Ticket and work tracking systems change. Adding defects to the backlog is not ideal because nobody is going to fix them, clearly.

Duplicating comments is not ideal either for the very reasons you listed.

Commit messages are not that great either, because there are so darn many of them. A single voice gets drowned out by the crowd.

Pick one of the files for this chart library to put the Big Explanation. In files specific to a chart that suffers from the defect, add a smaller comment explaining the conditions that trigger the defect, and refer curious readers to the chart library file containing the Big Explanation.

This allows you to record implementation specific information in comments at the location of the defect. It also gives you one place in code that divulges all the gory details.

Don't create defect tickets for things you have no intention of, and derive no benefit from fixing. Those work items will hang around long after the memory of why they exist has faded. Code sticks around longer. Keep it in code.

Answer 2

In this particular case, it would make sense to create a ticket in an issue tracker where the bug and the general workaround strategy are documented. Often it is possible to attach further documents to a ticket, such as stack traces or screendumps. In each affected source file, have a comment linking to the ticket and sufficient explanation how the workaround works in that file.

The advantage is that you keep a list of known bugs in one place (even if you're currently unable to fix them) and you can look up affected code files by searching for links to that ticket.

If you get around to fixing the bug (or if the library supplier delivers a fixed version) that lookup may be useful to find the code where now unnecessary workarounds can be removed.

Answer 3

Would it make sense to reference the one comment from the other files.

"For addition information on this bug fix see My.Project.Namespace.Class"

Or if the namespace and class names may change then reference a work item, wiki page, or ticket, or mark up file.

Keep it Simple, as well as DRY.

Answer 4

I would argue that in most cases, comments are anti-patterns. The fact that one has to justify some piece of a code with an accompanying comment means that the code is not-so-readable. You also rightly pointed out that comments and code could go out of sync.

The antidote to writing comments could be readable code together with well-named unit tests for the changes you are making. Unit test names can be as verbose and as English as you like.

At the same time, I'll acknowledge that there are certain cases when you can't fight off the urge to write a comment. For eg; there could be a gotcha that you'd somehow like to justify. I'm not sure whether the scenario you described in your question fits in to this category. Nevertheless, in such cases, use your commit messages to talk about why you made that particular code change. If you're using git, make sure that the first line of the commit message is short and sweet. Place a newline and then your five-line comment could be put in. I'm not a fan of capturing this information in ticketing systems since they would be like twins separated at birth. Commit messages are perhaps the closest "meta" for the code.

Answer 5

Have you considered to create an interface class to the external dependency? So you have a piece of code between your internal logic and the external library.

In the interface code you can implement the workarounds (may be in additional classes).

That would solve a few issues:

• Your chart implementations would be clean, the just generate the chart
• Your interface class is a clear separator
• Your fixes for the bugs are separated so they are also clear (you could comment here to explain why you did those fixes)
• (bonus) It allows you to maybe someday move to some library with less issues.

Reason I came to this thought was both the DRY principle you mentioned but also the Single Responsibility Principle. Your chart implementations are not responsible for covering issues with the library.