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

[Maxi Contieri]

Documantation is always obsolete

Write good tests instead
Documentation lie, Tests can't lie
Documentation is dead, tests are alive

[Jean-Michel 🕵🏻‍♂️ Fayard]

Nice false dichotomy that you have there

In real life, if I don't understand your readme, or can't follow your first tutorial, I'm not gonna read your unit tests.

[Maxi Contieri]

That's ok to me.
I don't use code without coverage because I don't know how or if it works.
I will upload a new github repo documenting how to break RSA and to prove P=NP since I can document anything.

I think we can both be safe as long as our roads don't cross.

[Jean-Michel 🕵🏻‍♂️ Fayard]

Just to be clear, your answer to "A xor B is a false dichotomy" is "B without A doesn't work"?

[taijidude]

I strongly disagree. Unit Tests are a good source of additional documentation but should not be the only one.

[Maxi Contieri]

In which other way would you add functional documentation?

[taijidude]

Good question. One thing that comes to mind is diagrams. Granted not perfect, but a good diagram can be okay to maintain and offer clearity. Even better if i can generate it from my Code. But i know the answer is vague.

[Maxi Contieri]

IMHO, Diagrams are for human to human comunication

Used to document sofware is yet another code smell

Code Smell 47 - Diagrams

Maxi Contieri ・ Dec 9 '20 ・ 2 min read

#oop #codenewbie #tutorial #webdev

[Maxi Contieri]

Code Smell 47 - Diagrams

Maxi Contieri ・ Dec 9 '20 ・ 2 min read

#oop #codenewbie #tutorial #webdev

you can add functional tests, contract testing, integration testing, cucumber, BEHAT and so on

All of them are alive and kicking. documentation is dead prose

[taijidude]

Again, disagree but i see your point. Having diagrams doesn't make it automatically good. The main thing that documentation has to do is communicate your ideas, design information to other humans. I'm a visual guy. When i want to understand something or discuss with colleagues i start drawing.

[Maxi Contieri]

I'd love to discuss with you using diagrams since we are both humans

[taijidude]

Okay, my pleasure. ☺️

[JoelBonetR 🥇]

I also find tests necessary but tests and doc cover two different things.

Documentation is to provide ease to use for developers while tests "explain" behaviour. You also can add documentation inside your tests and point to the issue or whatever.

On the other hand, there are ways (linter, CR) to ensure both that people add doc plus that they update the doc along changes in functions/methods.

If we're talking about a different kind of documentation (wiki) then yes, this -almost- never ends well.

[Maxi Contieri]

In My code reviews, I usually remove Doc documentation since they bring no value and are in danger of obsolence. No documentation is better than useless documentation

see

Code Smell 05 - Comment Abusers

Maxi Contieri ・ Oct 24 '20 ・ 2 min read

#codenewbie #tutorial #beginners

and

Code Smell 146 - Getter Comments

Maxi Contieri ・ Jul 2 ・ 2 min read

#javascript #webdev #beginners #programming

[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 🤷🏻‍♀️

[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

[JoelBonetR 🥇]

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.

[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

[Mihail Malo]

That's where doctests come in.

[Maxi Contieri]

What is their added value?

[JoelBonetR 🥇]

What do you understand as "value"?

[Maxi Contieri]

The add value that doctests add

If I see a point I will start to use them instead of removing them

[Mihail Malo]

Usage examples that never go stale because they are tests that run.