How to make sure the application source code has a proper documentation for new programmers?

Question

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.

Answer 1

Unfortunately, there is no way to "properly" document source code. Here are the main reasons:

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

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

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

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

5. 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 lie
• They must be simple (4-10 lines of code)
• They explain each feature of the code one after the other
• They 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?

Answer 2

In one word - Process. I work in the aerospace industry, there is a process that requires certain artifacts are generated as part of the software development cycle. Yet another process within QA ensures that these artifacts are generated. A review process ensures the generated artifacts meet the required level of detail and accuracy. Yet another process emasures that success of the other processes etc.

It's far from perfect, it's not cheap, and takes a lot of effort to get anything done. It is possible for a developer to maintain a multi-million line code base without reading and understanding every line of code. I know of no other way to achieve this. The "code is gospel" coders fail miserably when faced with these life critical, real time complex systems. The documentation is not a 100% accurate reflection of what the code does, but it is closer description of what the code should do than the code. Therefore, if the code does not do what the doc say it should, the code is probably wrong.

We do not use tech writers; however, I believe we should - programmers are not always good writers of English, and empolying a tech writer to turn clumsy technobable into concise English would be a small investment for large gains IMHO.

Answer 3

I don't like documentation. It can lie, the code can't. By all means have documentation on the higher level concepts of the application, but documenting code? That's a big sign that your code is not clear.

I do however code in a high level language (C# mainly) that is pseudo English, others using more lower level may disagree.

Answer 4

I'm not aware of anyone using tech writers for purely internal documentation, the problem, especially for lower level stuff, with written documentation is keeping it in sync with what the code actually does, therefore written documentation is best target at the areas which are going to change the least i.e. the high level concepts of what the software does and why? what assumptions have been made, and what alternative designs have been discarded. Tests can be used to document the low level stuff and running them will tell you if they are in sync with the code.

For low level understanding of how a function/ method or class is meant to work unit tests are the best form of documentation for the simple reason that running them tells you whether they are in sync with the current code base or not. not something you can check with comments or text based documentation. automated unit tests are pretty much a must for many reasons anyway.

Integration and system tests can help document other things, how is the system envisaged to be used? what is the workflow an operator will use? automated integration and system tests are nice to have, but at the very least you want scripted manual tests. You may also need some additional description around this level if/when it is not possible to test every case, you then need to capture the intent some other way.

There are things that tests are not so good at documenting, architecture springs to mind. Architecture can be reasonably documented with UML, though in a low process shop 5 minutes with a whiteboard and an experienced dev is probably good enough.

Answer 5

Developers at big corporations like IBM, Microsoft, and Google follow code conventions to ensure well-written code and conduct code reviews to discover poorly-written code. Poorly-documented code qualifies as poorly-written code.

The primary source of technical documentation for software is the source code, any other documentation is secondary. Technical writers are typically employed to convey technical (and possibly marketing) info to users (brochures, manuals, and tutorials). Developers should be satisfied with well-written source code (and API documentation).

A well-practiced programmer should have mastered a habit of documenting their code during and not after coding (in the same manner that scientists document their experiments during-not-after). Code documentation should be correct, clear, and simple. Code itself should be self-explaining to reduce the need for long paragraphs of explanation.

There are tools you can use to generate API documentation from source files for popular programming languages like Java (javadoc), PHP (phpdoc), Python (pydoc), and Ruby (rdoc). And also tools that you can use to analyze your code for common coding mistakes including lack of documentation.