Why should you document code? [duplicate]

Question

Possible Duplicate:
“Comments are a code smell”

I am a graduate software developer for an insurance company that uses an old COBOL-like language/flat-file record storage system. The code is completely undocumented, both code comments and overall system design and there is no help on the web (unused outside the industry). The current developers have been working on the system for between 10 and 30 years and are adamant that documentation is unnecessary as you can just read the code to work out what's going on and that you can't trust comments.

Why should such a system be documented?

Answer 1

Why should such a system be documented?

In my opinion, any system that is used productively and is supposed to be maintained by people, should have documentation at reach of those people who are responsible for its support. The reason is, simply because:

1 - Not all developers have the same IQ - You want every one to get it not only smart John

2 - Not all code is obvious, complex algorithms are not quite readable by all

3 - Business rules, while may be readable, may not alone show why they are there. Take for example this line in a reporting application:

if (lastname>="ZZ") then goto loop

it is somewhat clear to the reader 'what' is happening but not 'why' this is the case?

4 - Finding out details take long time, it is a waste of business money

5 - Dependency between pieces of the system may not always be obvious. Speciall in batch processes where each job looks like an independent program but the execution sequence is a package that must be processed according to certain rules (like monthly runs, etc.)

6 - Documentation should help you understand logs and whether the results are correct or not.

7 - When you understand the function of each component you can answer business questions. Say Suzan calls from accounting and asks why are we missing 5 checks this month? Some programmers may respond, well, I ran the job and gave me no error - This can't help Suzan. If you know which part of the system does the data extraction for processing the checks and then know what are business rules applied to qualify a check to be printed you can provide an useful answer - Assuming there were no bugs.

Remember that documentation go way beyond the comments that are inserted in code. They include ERD, Business Requirements documents, Design documents, etc.

In short, good documentation gives the developers the necessary control to maintain a system.

Answer 2

The developers of that system are just trying to protect their job.

If the code is well-documented and understandable, then the developers are easily replaceable. Obviously, if the code is completely lacking in documentation and is indecipherable except to only those trained in the arcane COBOL arts, then it's not so easy for those developers to be removed and replaced.

As you said, those developers have been there for over a decade. They are probably making well over $100K, probably closer to $200K. I'm sure there is a temptation by managers to replace them with junior developers straight from college (or off-shore developers) who will make 1/2 to 1/3 the salary.

Answer 3

This is of course depending on the complexity, but in general I would say the answer is quite easy... Yes! You say it is a COBOL-like language, how many people knows this language?

If this developer have a heart attack or becomes unavailable, who will be able to explain when someone new needs information about the design?

Time is money, to get up to speed and start do something that makes profit. It goes quicker to browse through the documentation to understand how things are supposed to work before messing up the code.

If you need to bring in some external help, it would be both cheaper and quicker if they can read the documentation.

There are other things you can't see by looking at the code itself. Thoughts about future expansion. Some code might look really stupid but is designed in a way for a coming feature or expansion.

If the company's business is relying on this program, you really want it to be documented so you can fix problems fast if something happens (for example if the key designer get pissed and leaves).

We all find it a pain in the 'A' to write documentation. I can recommend auto generated documentation such as Doxygen, a great free tool that reads your code and draws call diagrams and collects comments into either a Help file or a HTML manual. I don't know if it can handle your Cobol-like language, but there are scripts and variants that extends it to handle more languages.

We usually made a lose design document before starting a project, then we document with Doxygen style comments in the code. That was effective enough to bring in new people up to speed quickly...

Answer 4

Theres several aspects to this question.

There is an issue with comments in code, is that they introduce an overhead on maintanence programmers, in that when they change code, they also have to change comments. Now Sometimes comments are in the code that calls a function/method about how that method behaves, so does the maintanence programmer even know about these comments to update them? probably not.

In this case, is seems that all the other existing programmers find reading the code easier than trusting out of date comments.

Is it possible the difficulty you are having understanding the code is that the programming languange is not familiar? and its not comments that are needed, but training, practice and experience in this programming language is the real issue?

Answer 5

I'm not sure I would agree that comments/documentation are unnecessary in general. I've observed, though, that over time as my team and I have become better at writing code we have been able to decrease the amount of comments. E.g. If a method is called ProcessFile() why would you want to add a comment that states "This function processes a file"?

There are, however, cases where comments can be extremely helpful. For example when the purpose of a particular statement is not obvious. To take an extremely simple (simplistic?) example: You may implement a division by two as a right shift of bits.

The amount of comments probably also depends on the programming language you use. For example compare assembler code with code written in a higher level language such as Java or C#. Again, I suspect there is a spectrum here.

I would agree, though, that comments cannot be trusted in general. The reason is that in particular with code that has a certain age, the code may have been modified while the comments are still the same. Code and comments are out of sync. Worst case this type of comment may lead a developer to wrong conclusions. My recommendation would be to always be cautious with using information contained in comments.

In summary I think good code requires less comments and in the extreme case could be self-explanatory. To move towards better code in my experience test-driven development (TDD), simple design and merciless refactoring are the best tools. None of these tools, however, replace proper thinking to make appropriate and reasonable choices.