The Myth of Self Documenting Code
Or, how I learned to stop worrying and love the comment.
This article is a response to Joe Eames' article on self-documenting code. If you haven't read it yet or aren't familiar with the concept of self-documenting code, please check out the article [here].
I consider self-documenting code to be a myth and perpetuating it to be dangerous (especially to new programmers).
Before we get into why, let me summarize the two primary arguments for sefl-documented code:
- Comments that explain what the program are doing are redundant. As code changes, comments can also become out-of-date and stale, making the code harder to maintain overall.