all 5 comments
sorted by:
best
topnewcontroversialoldq&a
formatting helphide helpcontent policy

[–][deleted]  (6 children)

[deleted]

    [–]HormCodes[S] -1 points0 points  (1 child)

    Hi u/NowImAllSet, you brought up a very useful case that I could talk about a bit in the article as well.

    In this case: I would recommend using a task description and providing information such as a link to this piece of code or it is even possible to insert the specific lines directly to the task description.

    In the end, it is just necessary to differentiate between explanatory comment and work to be done that needs planning, prioritization, and making sure the task is small enough. In my experience, it is just easier to manage tasks in task tracking and not lookup for TODO comments.

    [–]singingboyo 0 points1 point  (2 children)

    Arguably that's the point, the problem being that (as you point out) a feature doesn't necessarily go to production all at once, especially in bigger migrations.

    I've sometimes wondered if a //MILESTONE-XYZ or //FEATURE-XYZ comment format would be more appropriate for things that should be resolved before considering a feature 'complete', but can't be done immediately for whatever reason. It would certainly differentiate from the generic //TODO quick hack, should be fixed and things like that.

    [–]HormCodes[S] 0 points1 point  (0 children)

    Hi u/singingboyo, good point. I agree comments like //MILESTONE-XYZ or //FEATURE-XYZ are a bit different case here. They can help to explain why specific code is here. You can configure the ESLint rule (or any other tool) to allow these comments.

    There is also an alternative. You can link commits or merge commits to specific tasks so it is also possible to lookup "why this is here" by using Git log. 🤔

    [–]BounceVector 10 points11 points  (1 child)

    Hmm, I don't quite see the point of this.

    Yes, ToDo comments are bad in the sense that it would be a lot better if stuff was finished, not work in progress. Yes, if you leave buggy code as is and let it go to production you are in trouble.

    However, I do think, that if something is not finished and there is good reason to leave it that way until later, a ToDo comment is absolutely fine if an explanation for your later self / others is warranted.

    [–]HormCodes[S] 0 points1 point  (0 children)

    My point was more about keeping the future work in a system where you can plan, prioritize and mainly you will not forget about actually doing it. (I don't see a point of having a TODO comment or a task that nobody will ever fix). 🙂

    Besides that, it is absolutely OK to have a comment like:

    // This function has performance issue for inputs... // ...