DEV Community 👩‍💻👨‍💻

Omer Rosenbaum
Omer Rosenbaum

Posted on

Is self-documenting code a myth?

meme on documenting code. "when u revisit function u wrote months ago and now it makes no sense and there is no documentation"

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?

Top comments (1)

Collapse
 
curiousdev profile image
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!

We want your help! Become a Tag Moderator.
Fill out this survey and help us moderate our community by becoming a tag moderator here at DEV.