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
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
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
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.
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
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
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.
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
One of the most salient features of our Tech Hiring culture is that there is so much bullshit. Everyone knows this. Each of us contributes his share. But we tend to take the situation for granted.
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
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.
One of the most salient features of our Tech Hiring culture is that there is so much bullshit. Everyone knows this. Each of us contributes his share. But we tend to take the situation for granted.
No Documentation is worse IMO, but I do think there some stale examples in the wild that are so egregious, it would be better if people didn’t stumble upon those docs.
Stale docs are annoying but if the documentation has a contributor workflow, then they can be quickly updated. No docs require more work to correct.
In my opinion, having no documentation is much worse than having outdated documentation. It is possible to extract a point from the old document, but without the document it will be very difficult. However, sometimes old documents are also misleading. Especially if they are not updated. But it is better than having no documents.
If the differences between the documentation and reality are minor, stale documentation may still help. But that’s often not the case, so then it’s misleading and you’re maybe better of with no documentation at all.
Where possible, I prefer Living Documentation directly connected to automated tests, or generated from production code.
Smiling person, father of two, Husband, Senior Developer/Architect (in that exact order, it's important)
Experience in development since 2004
Linux user and advocate since 2001
Have a documentation with 2 articles about the same thing. And each of them make you think a part of it is right, but your have to go deep dive the code. To understand it's even worst that you think.
Smiling person, father of two, Husband, Senior Developer/Architect (in that exact order, it's important)
Experience in development since 2004
Linux user and advocate since 2001
I am an OpenEdge (aka Progress) developer that loves clean code and good looking applications that are easy to use. My main pet project is the Progress DataDigger
Welcome to our profile. We are a video game marketing agency. We provide professional SEO and marketing services for the gaming industry. Please visit our website.
Documantation is always obsolete
Write good tests instead
Documentation lie, Tests can't lie
Documentation is dead, tests are alive
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.
I strongly disagree. Unit Tests are a good source of additional documentation but should not be the only one.
In which other way would you add functional documentation?
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.
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
Code Smell 47 - Diagrams
Maxi Contieri ・ Dec 9 '20 ・ 2 min read
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
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.
I'd love to discuss with you using diagrams since we are both humans
Okay, my pleasure. ☺️
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.
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.
Just to be clear, your answer to "A xor B is a false dichotomy" is "B without A doesn't work"?
No Documentation is worse IMO, but I do think there some stale examples in the wild that are so egregious, it would be better if people didn’t stumble upon those docs.
Stale docs are annoying but if the documentation has a contributor workflow, then they can be quickly updated. No docs require more work to correct.
In my opinion, having no documentation is much worse than having outdated documentation. It is possible to extract a point from the old document, but without the document it will be very difficult. However, sometimes old documents are also misleading. Especially if they are not updated. But it is better than having no documents.
Depends on what kind of stale.
Stale as in missing information, incomplete, but accurate for what little it does describe? Great! --- I want more but I'll take what is there.
Stale as in wrong? Nobody wants that!
If the differences between the documentation and reality are minor, stale documentation may still help. But that’s often not the case, so then it’s misleading and you’re maybe better of with no documentation at all.
Where possible, I prefer Living Documentation directly connected to automated tests, or generated from production code.
Have a documentation with 2 articles about the same thing. And each of them make you think a part of it is right, but your have to go deep dive the code. To understand it's even worst that you think.
Here I'm talking by experience.
stale documentation because it gives wrong expectations
No documentation. With stale documentation i have at least clues where to look.
I depend on what is the documenation about.
If it's about code, then I prefer to have nothing, but also the time needed to understand the code, code is almost always self explanatory.
But then, if you have nothing and what were looking for is about either:
Think about a service that make external calls to a black box. Or a client that calls an old APIs you have. Having a contact name is priceless.
In such cases, I always prefer to have a walking dead documentation than nothing, because the code cannot help me.
Defensively, with no docs, at least you know exactly what you have
I'll go with stale documentation. If you try to understand from zero its still better than understand it wrong.
I don't know what's worse. Ideally, the site is up-to-date in all respects.
Show don't tell
Working examples are always better than explanation. If you're too lazy to write a test case, example code can act as a smoke test too.
Both
Worse is when my tummy hurts