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.
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. :)
I'm a software architect the long way round, by way of system administration, then configuration management, then devops, then software engineer. Also a fiddler, photographer, and family man.
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.
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
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.
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. :)
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.