# When to leave code comments Created: [[2024_01_28]] 11:13 Tags: #software #teams When should you comment your code? Code is the language of describing how to solve a problem. But it doesn't always give context on what problem it is solving, much less **why** it is solving it. I tend to lean towards not commenting code too much, preferring to use more clear variable names and idioms to make code be as readable as possible by default. But [this article](https://max.engineer/reasons-to-leave-comment), gives some good situations when commenting code should be done: - An odd requirement - We've all had to write something a little weird because we needed something to work in a very particular way - It was non-obvious and took research to solve - If it isn't something people deal with in their day-to-day it is helpful to explain how that solution was formed and what formed it, use links. - Multiple options were considered - There were multiple options, but only one was chosen, state why that was, what tradeoff was made - It came up in code review - If someone had to ask why during a code review, it likely means that it was non-obvious. ## References - Stolen from: https://max.engineer/reasons-to-leave-comment