Tech Lead/Team Lead. Senior WebDev.
Intermediate Grade on Computer Systems-
High Grade on Web Application Development-
MBA (+Marketing+HHRR).
Studied a bit of law, economics and design
Location
Spain
Education
Higher Level Education Certificate on Web Application Development
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.
Learn something new every day.
- I am a senior software engineer working in industry, teaching and writing on software design, SOLID principles, DDD and TDD.
Location
Buenos Aires
Education
Computer Science Degree at Universidad de Buenos Aires
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
Tech Lead/Team Lead. Senior WebDev.
Intermediate Grade on Computer Systems-
High Grade on Web Application Development-
MBA (+Marketing+HHRR).
Studied a bit of law, economics and design
Location
Spain
Education
Higher Level Education Certificate on Web Application Development
Learn something new every day.
- I am a senior software engineer working in industry, teaching and writing on software design, SOLID principles, DDD and TDD.
Location
Buenos Aires
Education
Computer Science Degree at Universidad de Buenos Aires
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
Tech Lead/Team Lead. Senior WebDev.
Intermediate Grade on Computer Systems-
High Grade on Web Application Development-
MBA (+Marketing+HHRR).
Studied a bit of law, economics and design
Location
Spain
Education
Higher Level Education Certificate on Web Application Development
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.
Learn something new every day.
- I am a senior software engineer working in industry, teaching and writing on software design, SOLID principles, DDD and TDD.
Location
Buenos Aires
Education
Computer Science Degree at Universidad de Buenos Aires
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
Learn something new every day.
- I am a senior software engineer working in industry, teaching and writing on software design, SOLID principles, DDD and TDD.
Location
Buenos Aires
Education
Computer Science Degree at Universidad de Buenos Aires
Tech Lead/Team Lead. Senior WebDev.
Intermediate Grade on Computer Systems-
High Grade on Web Application Development-
MBA (+Marketing+HHRR).
Studied a bit of law, economics and design
Location
Spain
Education
Higher Level Education Certificate on Web Application Development
Learn something new every day.
- I am a senior software engineer working in industry, teaching and writing on software design, SOLID principles, DDD and TDD.
Location
Buenos Aires
Education
Computer Science Degree at Universidad de Buenos Aires
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.
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
and
Code Smell 146 - Getter Comments
Maxi Contieri ・ Jul 2 ・ 2 min read
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 🤷🏻♀️
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
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 notdon'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.
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
That's where doctests come in.
What is their added value?
What do you understand as "value"?
The add value that doctests add
If I see a point I will start to use them instead of removing them
Usage examples that never go stale because they are tests that run.