> Let me know what corner cases you thought about when you wrote this. We actually rarely use comments in code. The best way to reflect the corner cases are te

> Let me know what corner cases you thought about when you wrote this. We actually rarely use comments in code. The best way to reflect the corner cases are tests. It is the comments codified. > but it can never say why Usually people don't need to know why on small piece of code unless it's a high-level stuff. For high-level stuff we have architecture decision records (ADR) which records the motivations and situations. But we also keep it very short or people would never read those. > "Nobody ever updates comments, so they're always out of date" - don't hire such people. That's a really high standards. It's almost like "We have bugs", "Well, then don't hire people writing bugs"... There are many ways of breaking comments. For example, someone changed module A, then the properties on module B changed because of A. If it's a test it will reflects on CI, but if it's a comment there's almost no way for people to realize that.