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.
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.
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.
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.