Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 2 Next »

Question: How does one decide whether to open a GitHub issue or leave a TODO in the code?

Answer: I would say that often my choice to open an issue or leave a TODO isn't very scientific. Leaving a TODO is easier than writing an issue, so sometimes the decision is made out of pure laziness :) But in an ideal world, I would try to follow these guidelines:

  1. Create BOTH an issue and a TODO if possible. Open an issue explaining the problem, and then reference the issue number from a TODO comment in a relevant part of the code. For example: . I typically use this approach if I discover an important issue in the process of writing a PR, but it's too large or difficult to fix in the current PR.

  2. If it's not clear exactly where in the code the problem is or where a fix should be implemented, then opening an issue without a corresponding TODO is fine. It's also perfectly fine to just open an issue even if you know where the fix should go but you don't have an in-progress PR open for that part of the code. In that case, you can still reference line numbers or a GitHub link in the issue description.

  3. If, in the process of writing a PR, you have an idea for something that might improve the existing code but it's not very important or urgent, then I think it's ok to just leave a TODO without opening an issue. This can be dangerous, though, since it's easy to forget about TODOs. On my team, we typically make a point of grepping for TODOs at the end of a release cycle to make sure we didn't miss something important. I also leave TODOs without a corresponding issue number if fixing it would require more than a single issue's worth of work. For example, in this comment I mention that we should "take latency into account". Making the optimizer aware of latency is a big task that is on our product roadmap but may not have a corresponding GitHub issue. TODOs can also be helpful to explain a hacky implementation so that a future reader of the code can improve it or at least understand why the original implementer made the choice that they did.

  • No labels