DEV Community

Discussion on: What's worse: Stale documentation or no documentation?

 
joelbonetr profile image
JoelBonetR 🥇

So instead enforcing the documentation and keeping it up to date you prefer to remove it... What can go wrong.

It may not bring "value" but it speeds up future developments and maintenance for sure 🤷🏻‍♀️

Thread Thread
 
mcsee profile image
Maxi Contieri

ussually I just don't remove it. I write a self documenting test instead.
Then I remove th comment before it gets obsolete

Maintenance is granted as long as you have automated tests.
You can add a bunch of documentation and yet bring zero maintenance value since developers don't read documentation. But if they break a test, they will have inmediate feedback

Thread Thread
 
joelbonetr profile image
JoelBonetR 🥇 • Edited

Well, it depends on the environment/language till certain point but as I already said, documentation can be enforced through lints or any other tool and you'll get feedback for sure.
check this as example.

On the other side, tests should not don't apply to every single function you have. Tests are meant to ensure behaviour (public interface) while documentation in functions is meant to add information to the implementation details.

That's the reason I said both are not exclusive neither they are replaceable between each other.

Thread Thread
 
mcsee profile image
Maxi Contieri

I see your point in your article.
If it keeps updated automatically I am ok with it.

Implementation details are accidental and can change as long as no external contract is broken.
documentation should be the exception for a very small use cases, IMHO