Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

  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: https://github.com/cockroachdb/cockroach/blob/d52f071bb5277920b593711fc810fc092a2a2f24/pkg/sql/opt/exec/execbuilder/mutation.go#L155 . 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. In the example you gave above where I reference "taking For example, in this comment I mention that we should "take latency into account", making . 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.