[kayo_20211030]

If the documentation is in the code, it's a helpful way for me to remember what I did, and why - so I do it. Although naming is super important, I've found that what I consider to be an obvious name can be perplexing or even confusing to others. Extensive inline documentation really helps here. It's more conversational, you can put in some extra relevant information, even present context and examples. It helps both me, a future me (important), and some poor anonymous future developer responsible for making changes better understand what's going on. This style is also grep-able and amenable to dev tooling intervention. If the documentation is independent of the code, there are some challenges. "non-attached" documentation is notoriously difficult to maintain. Even with the best will in the world it atrophies over time, becomes unreliable, even contradictory of the code itself. This style of documentation works best for top-level designs, where it's not expected that many future edits are required; and where there is a manager or curator who's willing to pound the table to ensure its maintenance.