> Explaining why the most obvious code wasn’t written. (Design decisions)<p>This is actually the most important thing in this article. The technical why of things are often overlooked in today's software development. It rarely is the problem until the original maintainer moves out to other project. Non-technical contributor sometimes won't or can't be bothered with it because either it is pretty complex, they have a lot in their plates doing non-technical stuffs, or both.<p>While commenting on the what is DISCOURAGED because 1.) comments can be quickly outdated and they are not tested/compiled 2.) they can be replaced with self-documenting code, commenting on the why must be ENCOURAGED, unless the software has a dedicated technical manuals / design document, which is pretty rare these days.<p>> The problem with comments is that they have no compile-time check and tend to be forgotten. It’s very easy to change your code but forget about the comments.<p>I write a bit of Rust and they have partial comment check on compile time. We can write example in the comments and they actually runs and get converted into a documentation. Neat!