All managers I worked for at some time or the other asked me to document my Applications. This involved creating UML diagrams, inline documentations and even code review.
UML diagrams are completely useless in my opinion. I submit the following reasons
1. Class diagrams can be reverse engineered. So you can get them when you want them. Can't see how documenting them helps.
2. Sequence diagrams only help as communication tool across major sub systems and no more. Trying to detail them out fails because they get outdated as soon as you start coding. The reason for that being that sequence diagrams cannot be compiled. Efforts to translate them to code fails almost instantly. One argument to create detailed sequence diagram was so that an architect could provide detailed specs to "dumb" programmers offshore. Apart from the fact that this allowed the architects to feel important because they are not drawing sequence diagrams instead of coding I do not know what was accomplished. Besides paying 2-3 so called dumb programmers "$35" an hour minus communication overhead which is obviously more than $0 I fail to see the cost savings.
Enough of ranting though. Having more programmers in the team helps indirectly in long term maintenance. In the above example while the architect could have coded more than just write sequence diagram there is an indirect benefit to the other 2-3 programmers. First of all contrary to popular desire to believe they are not "dumb". Secondly should the architect disappear else where to write more sequence diagrams they will provide enormous security to continue maintaining the code.
Which brings me to the last point. No amount of documentation can compensate for having 2-3 good developers on a project. Thats your only insurance against one of them leaving suddenly. You can document the code as much as you want but the new developers will take as much time to read your documentation as they will to make sense of your source code and if they are anything like me they will prefer the source code as " Source Code is never outdated".
So stop trying to save money by having only 1 guy no matter how smart to develop your system. Should he leave abruptly his documentation wont save you.
Wednesday, January 17, 2007
Subscribe to:
Post Comments (Atom)
2 comments:
...asked me to document my Applications.
What audience were the documents written for?
... they will prefer the source code ...
Will the source code tell them why the code was written?
There is no doubting that requirements specifications are necessary. Good functional documentation is necessary.
What I am questioning is the elaborate documentation of the source code so that some one coming in to the team can understand it. That may have made sense in days of procedural programming but these days of J2ee , .net programming with all sorts of framework its simply may not work.
I have browsed through lots of open source software. They have user documentation, also documentation on what problems a given OS software solves. But absolutely nothing to very little code documentation. If you want to participate browse through the code , that seems to be the message
Post a Comment