What motivates you to document/not document your code?

Question

I am facing this problem of NO DOCUMENTATION what so ever in my organization.

So, I am wondering, when ever I write my code I also try to write the important things, i.e. when some one reads my code, they can understand the context.

So my questions are:

1. What makes you document or not document you code?

2. How can we make developers document without making it a monotonous job after the initial thrust.

3. What are the critical things a developer should keep in mind while documenting, so that he/she keeps it crisp, concise, easy to read and easy to write.

Any more suggestions on documentation of code are welcome, marking as community wiki.

UPDATE 1

Ok, so I got some interesting answers from every one, but there is one problem, all of you guys are talking about code comments but what about company's intranet wiki pages, make it searchable on the wiki index and tutorials of how to re-use etc?

Answer 1

Write/architect your code in such a way that the need for documentation is minimal.

The idea is called self-documenting code. The class/method/variable names should be verbose enough to be understood easily and the structure of the code such that a context exists giving additional meaning to what you're doing e.g. separation of concerns.

Answer 2

No documentation can be caused by several things:

• unreasonable deadlines (programmer feels there is no time for documentation)
• lazy programmers (you could say "inconsiderate" as well)
• programmers who work alone and not in a team ( not always the case )

One of the BEST ways to reduce the need for documentation is holding developers to a single rule. ONE rule to RULE them all!! It will reduce the NEED for documentation.

THE RULE: All methods should be short enough to fit on one screen without scrolling.

Short, concise methods that do one unit of work each will be easy to read, are often self-documenting and are MUCH easier to manage.

Answer 3

1. I document code that is complicated and potentially confusing to myself or another coder in the future. I don't document code that to me, is itself a document. I don't see the need to document in English (or other spoken language), something which I or my audience can already read.

2. The same way we can make business analysts and project managers document requirements and specifications.

3. Simple Summary of a block of code, inputs and outputs, exceptions or errors that can be raised.

Answer 4

Short answer: Your next team developer is going to be 6'5" and very, very angry. More angrier when he sees the lack of documentation. He has fists of thunder.

Real answers to your questions:

• I document my code so when I go back I can understand it, and when we introduce a new team mate or someone else on the team didn't work on that branch, they can easily get what's going on before asking other questions (Even better, if you have great code you don't need much documentation!)

• If you are good, you will be motivated to do it. Simple enough?

• Don't over-document, keep it simple. Don't document the obvious ("In here we set var to be var2 .. useless documentation.) Document what the program should do, and what the expected result should be.

I bet there will be many more great answers.

Answer 5

Well, it really depends on how many people you have, how big the code base is and what sort of software you are writing (and perhaps who you are writing it for).

Some basic points.. Naming - code tends to be somewhat self-documenting if it is readable and a common naming convention used aids in making the intention obvious. There should be some attempt at documenting the overall design.. hopefully.

When to document.. I've a tendency to cover things off on a number of fronts, diagrams and supporting documentation (compiled during a design phase) followed with appropriate commenting in the code base. Typically I've found this helps most when you are exposing concepts which aren't obvious, or around code which is explicitly complex.

Lastly - I think it is important to find a balance between helpful commenting/documentation which adds value (e.g. helping others to interpret the design) verses overkill, i.e. mandatory documentation which adds no real value.

Answer 6

1. Go over your code later in time. Anywhere from a a few days to a few months later, you can get lost. Documenting your code not only helps you, but also others who you either work with or people you ask questions who have never even seen the code.

2. One word comments (if not in block form) can easily add a boost to how easy it is to understand code, and also writing code that is already named well in terms of your own functions, classes, etc. so you know what they're doing helps as well.

3. Use comment blocks for small blocks of codes rather than a few words at the end of every line.

Answer 7

To answer 3.

Your code should tell a story. In places where the code is written straightforward, with good naming conventions, little or no documentation is necessary. Developers should strive to, as Paul Sasik said, require as little documentation as possible. That being said, there are a few rules of thumb I have found lead to well-documented code:

1. Each major section of code should be documented. Functions, procedures, etc.. should have a block of comments explaining what the functions do, and if necessary references to where the algorithms come from (mostly in an academic code sense).
2. Anywhere that you need to do something that isn't clear, document what you are doing.
3. Use tags to indicate what the comment is for (the exception to this is in the blocks at the top of functions, etc..).. I tend to use the flags [todo], [kludge], [reference], [clarification]

4. Identify yourself in the comment. My comments tend to look like this:

   //[clarification]- MarkD 2010-07-01: comment explaing what needs to be claified.

Answer 8

1. Will I understand this is 6 months?
   Yes: Go to step 2
   Unsure: Go to step 6
   No: Go to step 6

2. Will someone else understand this?
   Yes: Go to step 3
   Unsure: Go to step 6
   No: Go to step 6

3. Am I working with others?
   Yes: Go to step 6
   No: Go to step 4

4. Will I be working with others?
   Yes: Go to step 6
   No: Go to step 5

5. Is the code self documenting?
   Yes: Stop
   No: Go to step 6

6. Document

Answer 9

I think the criticial thing is that you document at the same time as you write the code. Documentation and code writing shouldn't be a separate process, instead explain the code directly as you write it (or even before, and amend it then after you finished that section to correctly reflect the code). That way it is not much of a hassle but more a thing that is automatically done when you code.

I usually don't document too much, instead I try to keep my code clean. Having a good and clear coding style along with good variable names etc. helps a lot to have the code explain itself. Everything that isn't obvious should be documented on its own, in a clear and concise way.

I also often use documentation/comments to separate my code into sections. Things that belong together are visually connected in the code, and documented as a whole. That way, things that are not too related to each other are clearly separated by whitespace and comments and can be easier understood.

Answer 10

I assume that someone coming along after me will be able to read the code, so I don't typically explain what I did - they can read that. I do try and explain why I did it the way I did, where that might be less obvious.

Answer 11

I often have to write stored procedures for long, complex reporting scenarios where things are built in pieces to account for various possibly conflicting business/regulatory/legal rules in a compliance type report. I expect that an experienced SQL developer will understand the physical structure of the various selects, inserts, etc. but what they may not understand is what I was trying to accomplish with that chunk of code. So I will comment to say something like:

--MN law requires reporting on meetings not yet financially closed, this is supposed to find those.

Now the maintainer knows what this piece was trying to do and can evaluate whether it still needs to do that (MN law has changed and this is no longer needed) or if it didn't do it correctly (hey I'm not seeing all the MN meetings yet) and fix it. Without knowing the intent of a SQL statement you may know that it runs, but not if it gives the intended result. For a simple process, just the name of the proc often tells the intent (InsertNewUser for instance), but when things get complex and there are lot of different rules that are part of the rquirement, they need to be commented. Sometimes I write this structure out in comments first like an outline of what I need to do, then write the code.

For me undersatnd the intent of the code is critical to maintaining it and is the piece many people forget. Yes most of us can read code and oh, that does thus and such. But is thus and such what we really wanted it to do?

Answer 12

I like thinking of documentation in layers.

At the top, you have requirements. That's your system bible. It is a high level description of what the system is expected to do. Everything "the client" expects must be documented there. That may sound obvious, but the system must implement what's in the requirements document and nothing else. In doubt on a behavior, you should always refer to the requirements. If a requirement is not clear or ambiguous, the requirement must be reviewed with the client before you change the system.

Then you have technical specifications, the system blueprint. How are you going to implement each requirements, or groups of requirements? Here you can think of class diagrams, etc. You can think of this as a set of technical requirements used to satisfy the client requirements.

At the very bottom of the documentation stack, you have code comments. Requirements are known and technical specs have been defined. Code comments must explain how a class fits in the big picture. If you have complicated algorithms, variable comments and comments inserted between statements help understand how they work and why they are used. Follow javadoc or doxygen conventions.

In the end, the documentation stacks contains a lot of well organized information about your system. Everyone working on the project will have access to the same basic knowledge.

Some people just hate writing. They won't like any type of documentation. I think you should simply have them agree on the necessity and usefulness of documentation.

• Docs are good to make sure you are implementing what the customer wants.
• Docs are good to share knowledge between every member of a team: devs, testers, managers.
• Docs ensure all members of a team have a common understanding.
• Docs are complementary to a training. It's better to have both than have none.

Do not document for the sake of documenting. Keep things simple and well targeted. I am not convinced a wiki is a good idea. I personally always worked with Word and I wouldn't change that. It is still the best tool to quickly edit, copy, paste text and images together from various sources, fast.