5

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.

Community
  • 1
null
  • 155
  • 1
  • 7
  • 10
    What makes you believe code at IBM, Microsoft or Google is better documented than in other companies? – Doc Brown May 28 '12 at 06:57
  • @Doc Brown: lol, you got me. I assume they are better in documentation handling because they are big players. – null May 28 '12 at 07: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 07:27
  • @Doc Brown: how do you write the documentation? Write in form of code comment? or separate documentation in ms-word probably? – null May 28 '12 at 07:47
  • 2
    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 08:10
  • @Doc Brown: so you wrap that specific code pieces into a new method? wow, that sounds a good idea. I usually only wrap a piece of codes into new method if they are used more than one time (to avoid duplicated codes). – null May 28 '12 at 08:42
  • that's not my invention. Google for the SOLID principles in code, and for Bob Martin's books and articles about clean code. – Doc Brown May 28 '12 at 08:50
  • @Doc Brown: how do you deal with new guy? Do you just tell him to read and learn the codes? (then whatever happened, the new guy has to be ready for incoming tasks), or had you created application's architecture/specs docs and tell him to read it instead? – null May 28 '12 at 08:53
  • 1
    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 09:30
  • @Doc Brown: do you have experience with the high-level docs? If so, who usually write the high-level docs? The programmers themselves? Is the high-level documentation writing has their own timeline? – null May 28 '12 at 09:47
  • that depends on your team structure and the structure of your software system. Who in your team is responsible for the architecture of your system, which applications / modules / libraries you create, how the dependencies should be, how the data flow or the flow of events shall be etc.? Those person(s) should be responsible. – Doc Brown May 28 '12 at 10:28
  • I have a premonition. I ask my team in a meeting, "Guys, who wants to do the documentation, raise your hand!". One room become quiet, no sounds heard, just like in graveyard...Then I will say, "It's okay guys, let's decide it by drawing a lot". Suddenly, the room become loud and cheerful again :) – null May 28 '12 at 10:56
  • see also: [“Comments are a code smell”](http://softwareengineering.stackexchange.com/q/1/31260) – gnat Nov 08 '16 at 07:20

5 Answers5

5

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?

Aaron Digulla
  • 2,865
  • 21
  • 22
  • `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. – Erran Morad Jul 04 '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 07 '14 at 14:26
4

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.

jmort253
  • 9,317
  • 2
  • 35
  • 63
mattnz
  • 21,315
  • 5
  • 54
  • 83
  • multi-million line code-base? that is the sad state of affairs of the development world :( – Darknight May 28 '12 at 09: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. –  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
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.

Po-ta-toe
  • 167
  • 4
  • 6
    Code *can* lie! Read, Singletons are Pathological Liars [link](http://misko.hevery.com/2008/08/17/singletons-are-pathological-liars/) 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 07:22
  • 3
    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. – Po-ta-toe May 28 '12 at 07:34
  • 3
    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 08:45
  • 1
    depends what you mean by documentation, automated tests are one of the best forms of documentation – jk. May 28 '12 at 08:51
  • @jk: documentation that can make the new programmers quite understand the structure of application/source-code that they will deal with. Automated tests? Did you mean somekind of JUnit? – null May 28 '12 at 08:59
  • Any method called GetCustomer() that actually returns an Order is clearly lying (it does not do what it claims to do), unless you want to argue that words cannot lie, only people can. In which case I say "chase down the author and make him stop lying". – Frank Shearar May 28 '12 at 08:59
  • @suud yes, unit test document how individual classes and functions are meant to be used, integration tests can document higher level things i.e. whole APIs. As you get up into the architecture of the software you probably need some diagrams though whether this is in formal documentation or a 5 min session with the tech lead and a whiteboard is up to you – jk. May 28 '12 at 09:07
  • @FrankShearar the code is not lying. You are confusing a bad API with code. There is a difference between documenting code and documenting an API. If one is going to write a bad api, then one is going to write bad documentation. The minute you make a change to your code, your documentation is out of date. – Po-ta-toe May 28 '12 at 09:43
  • 2
    Undocumented code doesn't lie, it tells riddles. –  May 28 '12 at 11:15
  • @CarlSixsmith: An API is an _application_ programming interface. I do not know what "code" is if you're not going to include method names in it. Thus: if a method's name does not match what it does - if it actively misleads you - it is _lying_. – Frank Shearar May 28 '12 at 11:24
  • @FrankShearar If you look at just the API and that is lying - that isn't the same as looking at the code and that lying. The documentation and the API cannot tell you what the code is doing, only code can do that. Like I said above a public API should be documented - in terms of higher level concepts. But to do documentation on code is a complete waste of time. If you have to read documentation to understand what a piece of code is doing then that code is written badly, overly complex or contains some concepts of the language you are unfamiliar with – Po-ta-toe May 30 '12 at 07:48
2

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.

jk.
  • 10,216
  • 1
  • 33
  • 43
  • 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? – null May 28 '12 at 09: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) http://msdn.microsoft.com/en-us/library/dd286726.aspx – jk. May 28 '12 at 09:52
1

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.

  • 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. – null May 28 '12 at 12:59
  • 1
    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. –  May 29 '12 at 07:56