DEV Community

Discussion on: Not Documented, Not Done

Collapse
ashleemboyer profile image
Ashlee (she/her)

I love writing documentation. I know that most others don’t, and completely understand. However, that doesn’t mean you just get to avoid it completely. There are various things about our jobs that are hard, but we still have to do them. Documentation should be no different. I can’t stand it when places have 0 documentation and then tell you to “read the code” to figure it out. Cool, I can totally read code. But your code better be damn good and 100% legible. You better have some consistent docs on your functions. If you don’t, your code probably won’t reliably tell your story.

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.