4

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?

Community
  • 1
Edwin Tripp
  • 51
  • 1
  • 5
  • Why should you have instructions on products pack? But if it a kind of project that everyone put the finger on, than I agree, no need for document code. – devasia2112 Nov 25 '11 at 22:37
  • Are you talking about "formal documentation" using tools like Doxygen or Javadoc, or comments here and there in the code itself? – Maxpm Nov 26 '11 at 01:23
  • Formal documentation, the odd inline comment and design documentation (ERDs etc.). There is nothing to describe the implementation, only a document which describes the language provided by the manufacturer. It's a relatively small company (6 developers) and what I'm trying to get at is whether this is normal or more common that it ought to be? Is it worth trying to make them change their ways? – Edwin Tripp Nov 26 '11 at 07:59

5 Answers5

6

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.

stackoverflowuser2010
  • 2,736
  • 2
  • 18
  • 14
  • 1
    That may be the case but there is no proof. Could it be that this particular group of developers has been together for a very long time and simply are a very well-functioning team? I've seen and worked with people who have been on the same codebase for a very long time and the code bases was very understandable - from the team's perspective. I agree with you, though, that there are probably people who simply want to protect their job. – Manfred Nov 26 '11 at 00:31
  • 2
    yeah I find it far fetched that engineers even need to go to such means to "protect" their job. Firstly they can simply go somewhere else. And secondly nobody wants to code in cobol anymore so that should make their job safe enough. – Kevin Nov 26 '11 at 01:14
  • In this case, I would disagree that this is their intention. However, I am questioning whether I want to remain using their language. It doesn't particularly feel to be enhance my career prospects. – Edwin Tripp Nov 26 '11 at 08:05
6

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

MasterMastic
  • 268
  • 3
  • 13
NoChance
  • 12,412
  • 1
  • 22
  • 39
2

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

Max Kielland
  • 151
  • 2
  • Although using Doxygen for in-house COBOL-like language probably starts with 'teach Doxygen about the language'. – Vatine Nov 26 '11 at 08:46
2

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.

Manfred
  • 1,405
  • 1
  • 10
  • 13
  • 1
    If a method was called ProcessFile then I'd certainly hope to have some explanation of what kind of processing is done to the file. I'd have all kinds of issues with a developer on my team if their comment simply said "The ProcessFile method processes a file". I find documenting methods and classes can be very helpful to the developer, not just the maintainer. Even writing a simple summary of what a method does may reveal issues such as "the method name doesn't match what it is really doing" or "the method is doing way more than it should, perhaps it should be split". – Dunk Sep 20 '16 at 15:58
0

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?

Michael Shaw
  • 9,915
  • 1
  • 23
  • 36
  • The language itself is not so much of a problem. It revolves mostly around If..Do and While..Do. It's more to do with understanding how the many components of the system fit together and if/how making a change in one place will have an effect anywhere else. – Edwin Tripp Nov 25 '11 at 22:56