Possible Duplicate:How much documentation is enough? Do you know how the big IT company like IBM, Microsoft, or google make sure their application source code has proper documentation for future new programmers? What are their methods or tecniques? Do they tell the programmers to write documentation or hire a specialized technical writer to do that? Is the documenation in a separate file or in the source code itself (in form of annotation/comment)? Or is it another method that I don't know?I ask that because in my experience, I see most of the IT companies (in my country) are very lazy to impose the application-documentation-writing culture. So the problem always happens when a new programmer comes in, he will always face a situation where he is told to read and learn big chunks of source code with no documentation. Of course, he can ask the senior programmers to explain him, but sometimes the senior programmers are too busy with their works so they reluctantly want to help you, and sometimes it could be worse that the only one programmers that understand the code has already resigned. So you are left alone with the source code :(.Somehow I can understand the laziness of programmer to write comment or documentation, because the programmer's jobs are already arduous and tedious with their coding and testing sessions. Not mention the deadline-bell or angry boss that always haunting behind them. I can't imagine how painful and tiring for the programmer when after their long session of code-typing, they have to type again for the documentation.For technical writers, I never had a experience with them. I doubt how technical writer can be useful, because the one who fully understand the source code is the programmer himself. In that case, the programmer must accompany the tecnical writer to explain the source code.Note: I'm talking about source code or application development documentation, not the user documentation/guide which I think it's more properly written by system analyst or business analyst. The development documentation usually contains technical information about the development of the application such as: application features, class/function reference, class relationship diagram, database information, network information, etc. While user documentation is more about application's how-to information for the end-users.
How to make sure the application source code has a proper documentation for new programmers?
development process;documentation;source code;sdlc
Unfortunately, there is no way to properly document source code. Here are the main reasons:What do you know? If you're an apprentice, you'll need much more detailed documentation than, say, someone with 70K on stackoverflow and a gold java badge. How can you know in advance what someone starting at your company will know and what you need to explain in the documentation?How do you keep documentation and code in sync? Code is verified in many ways: Unit tests, code reviews, running it in production. If the documentation is wrong, someone has to read it and notice. This means docs age much faster than code and people quickly start to distrust and ignore it which makes it age even faster.When do you document? Early? That raises the chance that the documentation lies (see the previous point). Late? Raises the chance that it's not done - ever.What do you document? The 10'000 feet bird eyes view? Most useful and has the biggest chance to stay useful over time but useless most of the time - say when you hunt a bug.Why do you document? Just to make the management happy? What do they know? Or do you need to document because the code is so bad? How about writing readable code instead?I had some hopes with intentional programming but that didn't work out yet.My current approach, based on 25+ years of experience, is to write readable code in the first place and put documentation efforts into the unit tests:The unit tests can't lieThey must be simple (4-10 lines of code)They explain each feature of the code one after the otherThey are quick to run (rule in our company is that all unit tests must run in less than 10s)People starting at our company can run in the debugger with 2-3 mouse clicks and see how the code works.The biggest advantage: You need to write unit tests anyway. Why not use them for documentation purposes, too?