
Comments Are Useful Lies - 4mpm3
https://medium.com/young-coder/comments-are-useful-lies-f98c1c74476f
======
cborenstein
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](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...](https://medium.com/better-programming/daily-habits-to-turn-your-
git-history-into-valuable-documentation-15113e1bf312)

