3 ms·
Comments Are Useful Lies
- cborenstein 7y agoAwesome 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 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-your-git-history-into-valuable-documentation-15113e1bf312 https://medium.com/better-programming/daily-habits-to-turn-y...