Is self-documenting code a myth?

To answer our own question - yes. Do you agree?

If after a month you can barely make sense of the code you wrote, imagine how a junior dev joining your team would feel? Or even someone more senior going back to legacy code. Documentation becomes obsolete fast and eventually it renders itself useless.

Continuous Documentation
calls for creating and maintaining code documentation as a part of the normal development workflow.

The principles of Continuous Documentation require that documentation is:

1. Always up-to-date
2. Created at the right time
3. Tightly coupled with the code itself

So you created a bunch of documentation. Now what? How do you make sure it stays up-to-date?

This tech checks docs as code evolves, notifying you if your changes affect your documentation.

So, what do you think? Will the "self-documenting" excuse disappear once documentation is (much) easier to maintain and keep up-to-date?

Comments

[CuriousDev]

You should write code, which can be understood. Of course there can be exceptions, when this is not possible and you need to add comments for example (which then need to be kept up-to-date). But being able to use some tools for easier documentation is no excuse for writing code, which is hard to understand!