Take the 2-minute tour ×

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.

share|improve this question

marked as duplicate by Doc Brown, gnat, Walter, Jarrod Roberson, ChrisF May 28 '12 at 16:21


What makes you believe code at IBM, Microsoft or Google is better documented than in other companies? –  Doc Brown May 28 '12 at 6:57
@Doc Brown: lol, you got me. I assume they are better in documentation handling because they are big players. –  suud May 28 '12 at 7:17
There are a a lot of questions already here how good documentation should look like. IMHO the general consensus seems to be "less is better", "some docs are better than none" and "write code in a manner that it needs less docs". –  Doc Brown May 28 '12 at 7:27
Code documentation belongs into the code. I try to make my code as readable as possible. When I have the feeling that comments are needed to explain sub-structures in my code, I refactor it to smaller methods, each one with a name which explains the sub-task. And when there are still things which are not obvious, then, but only then, I write some comments into the code. I avoid to comment "afterwards". But that's all for me, you should be more interested in finding a good documentation process for your team. –  Doc Brown May 28 '12 at 8:10
you should also have some high-level documentation giving you a rough overview over the system. I prefer data-flow oriented diagrams for that case. But that is nothing each dev in your team should maintain constantly for itself. If your system has a database, a graphical model of the DB schema is also a good idea. The high-level doc will also make the start for "the new guy" easier. But when it comes to the abstraction level of code, all documentation for the code should be in the code, nowhere else. –  Doc Brown May 28 '12 at 9:30

5 Answers 5

up vote 4 down vote accepted

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?

share|improve this answer
How can you know in advance what someone starting at your company will know and what you need to explain in the documentation? Good point. Then, why can't we make docs for the person with entry level skills ? It will help everyone. –  Borat Sagdiyev Jul 4 '14 at 19:30
@BoratSagdiyev: What you often need is an overview (i.e. something that answers the question "where can I find...?" or "why should I do it this way?" But detailed documentation gets outdated fast (unless you can spend the effort to keep it current). A half-hearted attempt at documentation (i.e. "someone ought...") is just a waste of time and effort. –  Aaron Digulla Jul 7 '14 at 14:26

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.

share|improve this answer
Code can lie! Read, Singletons are Pathological Liars link by google dev Misko Hevery. Excerpt: "Here is the interesting part. If you are the person who built the relationships (code) originally, you know the true dependencies, but anyone who comes after you is baffled, since the friends which are declared are not the sole friends of objects, and information flows in some secret paths which are not clear to you. You live in a society full of liars." –  Amadeus Hein May 28 '12 at 7:22
The code in that case is not lying, the API is, there is a big difference. If I write a method call GetCustomer() that returns an Order, the code isn't lying, it is doing what I told it to. Writing reams of external documentation will not fix such idiocy. –  Carl Sixsmith May 28 '12 at 7:34
The code may not be able to lie, but it in anything bigger than trivial system it has insidious ways fo hiding it's secrets. –  mattnz May 28 '12 at 8:45
depends what you mean by documentation, automated tests are one of the best forms of documentation –  jk. May 28 '12 at 8:51
Undocumented code doesn't lie, it tells riddles. –  Baker Kawesa May 28 '12 at 11:15

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.

share|improve this answer
multi-million line code-base? that is the sad state of affairs of the development world :( –  Darknight May 28 '12 at 9:12
I don't think programmers have to write nice essays to say what they mean unless the audience is the end-user, in which case that would be the technical writer's job. –  Baker Kawesa May 28 '12 at 11:11
"You have not sufficiently documented your code in this ticket. It fails peer review." –  Frank Shearar May 28 '12 at 11:25

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.

share|improve this answer
That automated testings are kinda new for me so I cannot picture it how it can make the new programmers to understand faster the large and complex application code. Are automated tests kind of GUI tools that can show you the flow of applicaton code? –  suud May 28 '12 at 9:44
it helps understanding as it formally describes cases that are meant to work and meant not to work, and at the unit level can be though of a list of example of how to use various things. you can get automated gui test tools for automating systems/integration tests e.g. VS2010 (need premium or ultimate edition) msdn.microsoft.com/en-us/library/dd286726.aspx –  jk. May 28 '12 at 9:52

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.

share|improve this answer
Thanks for your information and shedding the light on technical writer. But usually programmers are chased by deadline, how come the documenting does not disturb the programmer's focus on finishing the code? In my experience, I kinda reluctant to write documentation during coding. I'm afraid my task will not finish on time. –  suud May 28 '12 at 12:59
How much more time would it take to for example make a cup of tea while explaining as opposed to making it quietly? Documenting and coding are part of the same task. You don't need to write an essay to explain your code, and if you do then you're probably better off without it. Just a few short simple comments explaining the jumble of code you just wrote. It won't tax your schedule if you make it a habit. –  Baker Kawesa May 29 '12 at 7:56
