Comments Are Useful Lies

Awesome article, thanks for sharing.

You make a great point that comments aren't trustworthy but can still provide a useful breadcrumb.

My thoughts are that an overall documentation strategy can include several lines of defense based on how narrow or broad the context you need is.

1. write "self-documenting" code using good variable names, encapsulation, etc.

2. write comments to explain anything non-obvious in a specific line or block of code

3. use git commit messages or git pull request descriptions to explain why a feature was built a certain way

4. use an external documentation source (I'm one of the creators of one called https://bytebase.io) to capture higher-level context like why we're working on this feature.

Recently wrote a blog post describing a strategy for 3 and 4: https://medium.com/better-programming/daily-habits-to-turn-y...