Documentation is one of those tasks where is very hard to calculate the ROI (return on investment). How can you know how much money you are saving by having good documentation if you do not have an un-documented version of the same project. In the same way, how are you going to compare the time you are saving by not documenting your projects if you have not documented your project and see how long it took.
No, I am not proposing you implement your projects twice, once documented and once undocumented to be able to compare. But the truth is, we do not think too much about documentation until we need it, and by then, it is way too late. So just in case we need it, let's implement a documentation strategy.
First and foremost let me explain that I am not talking about the help files you should write for your application users. This task is better left in the hands of professionals; your tech-pubs department. Your documentation strategy is for the code that goes into your application. This is a more technical documentation, and should be written by the same experts that write the code.
I haven't convinced you yet? Well, let me give you the reasons why you should have a strategy to document your code, and let's see what happens.
1. Complexity Is Best Explained In Plain Language
Despite all the post and articles you read before about how good code is self documenting, how good programmers are able to read and understand code like if it was their first language, and how a clear use of patterns will help you to understand the design and architecture of your application. The truth is that, with the exception of a very small elite group of programmers to which I do not belong, most programmers understand plain language better than any code.
Can a programmer with the right experience go through hundreds or thousands of lines of code and understand what they are doing? Sure he can. But, it is going to take him a lot longer than if he had a few UML class diagrams and some HTML help files describing the API's and their use.
"Wait a minute. Are you proposing to use UML?" Not really, but there are things that are better expressed in a diagram than in plain words (you know, a picture is worth a thousand words).
2. There Are Things Code Cannot Express
Customization points for classes; assumptions being made; side effects. These are all examples of things that cannot be expressed just with code. There are many more, and they will play a very important role once your code moves to maintenance mode.
You might be thinking, "that is what comments are for." Maybe, comments are your documentation strategy. If so, you should define it and make sure everyone understands it, so comments are actually added to the code.
Documentation and code can get out of synch if they are not maintained. Your team must understand the importance of having up-to-date documentation and make sure pertinent changes are made to it when the code changes.
3. Documentation As Training Material
Once in a while, you are forced to hire a less experienced developer, and you will be glad you have good documentation to get him up-to-speed. As he glances through the documentation, he might learn a few tricks that will allow him to become a better programmer. He can still learn a lot looking at code, but documentation is a supplement that can make his life and yours, easier.
New developers usually need some kind of Mentor that guides them through the learning process. You can save many mentoring hours if you have good documentation, and everyone will be more productive.
4. Finding What You Are Looking For
How many times have you implemented some functionality just to discover a few days later that someone had already written the same thing years ago? Undocumented code silently leads to duplication because in medium and big size teams, it is impossible that everyone knows about every single line of code written by other members.
There are many tools out there that will generate automatic documentation in a way that is easy to search and find exactly what you are looking for. This is a big time saver and promotes code reusability.
5. Because We All Forget And We Should Forget
No matter how many items you can keep in your memory (and I am not talking about RAM), sooner or later you will forget how a particular feature you wrote works. It is inevitable. If you did a good job writing the code, things will come back as you look at it, but most of the time, you will be glad you documented it.
There are times when you really want to forget. We all have code we wrote in the past that we do not want to remember. If you don't, most likely it means you have not learned much lately. In my experience, a developer presented with the exact same set of requirements at two different points in time will come out with two completely different solutions. Developers evolve and learn new things that makes them improve. This will drive them to solve the same problem in different ways.
Remember the assumptions I talked about in point two? These will also affect the outcome of the solution. Because we know now what we did not know then, we probably make different assumptions, and many times this will prevent us from understanding what we did in the past unless we have something to refresh our minds: documentation.
Conclusion
Documenting code is not fun. Maintaining documentation is a nightmare. You should plan your documentation strategy before starting a new project, so you can write the documentation from the beginning.
Your documentation strategy should be part of your code writing process. Merging both things together will make it less painful. Select a strategy that is accessible from the source code, find the right tools for you, and make sure everyone understand the importance of this task.
Documentation can bring new members up-to-speed; it can help you to refresh your mind when you need it; and it will prevent you from making the same mistakes over and over. It removes code duplication by exposing existing functionality to your development team, and it will help you to express the concepts that are hard to find and understand by just simply looking at the source code.
No comments:
Post a Comment