I like this culture too, and I wish it was more prevalent. Unfortunately, many developers today oppose it, writing explanatory code comments in natural language is seen as unnecessary, and documentation in natural language is seen as an afterthought.
I also suggest to younger people, try to write your own notes in full sentences instead of just bullet points. This is a good first step towards appreciating writing more, and in my experience helps you organize and remember your thoughts better.
>try to write your own notes in full sentences instead of just bullet points. This is a good first step towards appreciating writing more
Maybe. Writing bullet points was a good first step towards appreciating writing more for me. Writing well thought full sentences always makes me more anxious, and writing bullet points help me to actually write things down(even allowing me to refactor to full sentences when necessary, like when writing an email, slack messages or blog posts).
When I find code I don't understand the purpose of in code reviews I ask the author to document the purpose in the code so that the next person (likely future them) won't be confused by it like I was.
I find they often end up changing or removing it.
I have a feeling that writing explanatory code comments (as in _why_ something exists) about non-conventional code might come naturally when you've really thought something through. Where vice-versa undocumented non-conventional code might be a sign that they just got something working without really thinking about how it _should_ work.
> writing explanatory code comments in natural language is seen as unnecessary
It IS unnecessary. Having to write a wall of text to explain what your code is doing is one of the simplest code smells.
A little bit of very short comments is ok, but in general any verbose comment should always be for explaining the why, listing out some invariant, etc.
As a side note, another reason not to write comments about what the code is doing is because those comments then need to be updated too - and often they would not be leading to more confusion.
“This algorithm was chosen to ensure compliance with regulation XYZ.” “This planner takes into account inbound logistics delays and temporary out of stock conditions.”
I don’t ever want to read a comment like “Adds 1 to x, storing the result in y” but most wall of text comments are describing things that you can’t get from just reading the code.
Good documentation explains that which is not naively understandable. Most production-hardened code has lots and lots of code that deals with edge cases. A new employee might look at all the code that deals with the edge cases, think "this is needlessly complicated", and rip it out.
Sometimes you can handle this by writing out a test case and document the test case instead. Other times, you can't. It's context-specific.
I also suggest to younger people, try to write your own notes in full sentences instead of just bullet points. This is a good first step towards appreciating writing more, and in my experience helps you organize and remember your thoughts better.