feat: add doc for disabling SONAR rule preventing TODO comments

[jkuester]

Description

RSPEC-1135 prevents adding any TODO comments to the code base. The idea is to guard against merging unfinished code, but in reality, this is not much of a danger since those situations are easily identified via code review.

Instead, this rule is preventing use from using TODO comments to mark places in the code that will need updated in the future (but cannot be updated as a part of the current project). I think the benefits are not worth the downsides and we should just disable this rule.

License

The software is provided under AGPL-3.0. Contributions to this project are accepted under the same license.

[garethbowen]

This is my personal point of view and I'll go along with the majority if I'm outvoted, but personally I hate TODO comments. IMO they should only be used for things you want to fix before merging, which means having sonar pick this up during PR review is perfect. If you want to remember to come back and fix something after merging then it should be captured in a GH issue for visibility, tracking, discussion, including in release notes, etc etc. Putting it inline makes it hard to find, and in reality nobody ever goes back to fix it - if it wasn't important enough to fix in the original PR it's not going to be important enough to go back and fix next week.

[m5r]

I rarely use TODO comments but I agree that a GitHub issue is the better place to track future changes. With that said, they come in handy when the code can move around and it becomes harder to find the place we were supposed to change.
The most recent example is medic/cht-conf#623 where I added 2 TODO comments to pinpoint the place in the code where an eslint comment should be removed. In this case it's short-lived since I'm already working on the fix in a separate branch but the point is that it feels a bit too heavy to track this kind of change in an issue.

If we're going to keep this rule, I will need a solution to make Sonar happy in that PR because neither adding // NOSONAR at the end of the line or wrapping it with two lines // NOSONAR_BEGIN & // NOSONAR_END will make Sonar happy https://sonarcloud.io/project/issues?sinceLeakPeriod=true&issueStatuses=OPEN%2CCONFIRMED&pullRequest=623&id=medic_cht-conf&open=AZDBIkL15aSDoadCSmFw

[garethbowen]

@m5r I find it useful to use permalink when linking to code so you can find the code as it was at the time you wrote the issue. It can still be difficult to find the line but at least you know what you were talking about at a point in time!

Having // NOSONAR TODO is the worst possible compromise, so if that's the compromise, then let's remove the rule...

[m5r]

@garethbowen The PR containing the comment removal and the fix is already up for review, that's how short-term the // NOSONAR bandaid was.

Other than that occurrence, this rule hasn't bothered me when it shouldn't. I'm fine with keeping it but let's do something about the TODO comments lying around our repos

[jkuester]

Since it sounds like @m5r is okay with keeping the rule, and I am content with @garethbowen's explanation for why we should generally avoid TODOs (and no one else has spoken up), I will close this PR and keep the rule in place!

Thank you everyone for the discussion! 👏 IMHO this is how I hoped Sonar rule conversations could be conducted and now this discussion/decision is captured here in case we ever decide to revisit this.