DEV Community

Discussion on: Not Documented, Not Done

Collapse
aarone4 profile image
Aaron Reese

If documentation is an aid to understanding program flow and is non existent, I would propose that the time is better spent cleaning the code base so that the code is the documentation.
Meaningful named variables, classes and functions. Proper encapsulation and good unit test coverage. I.e. the tests are your documentation. Software invevitably changes over time and the documentation will not keep up. But in the absence of clean cidey, yes documentation can help.

Collapse
tiagodenoronha profile image
Tiago de Noronha Author

I disagree! :)
I actually have a good example that happened to me not long ago. One of my clients had a problem in production with a very old program (like really really old), so my boss wanted me to stop by and try and help them the best way I could under the circumstances.
When I got there, and asked them for documentation on what the project does, test plans to figure out what the project could do, or even a person to talk to. Of course, nothing :)
So we went with the approach you suggest: Clean up code. We couldn't do major changes but we did some.

If you only knew the business rules we broke while changing one line of code... That we could have avoided if we had some sort of documentation. :)

Thread Thread
leibowitzsam profile image
Sam Leibowitz

Yeah, I'm with you on this one. And this problem only gets worse when you're working on a large project involving multiple teams and multiple interlocking services. Every time you see a call in the code, there's a chance that it will be to consume a service in some other, equally poorly documented program,and figuring out how it's supposed to work is that much harder.