Is it efficient to attach a comment on every function? [duplicate]

Question

I moved to this company recently, and my first reaction of the development process leaves me with doubts.

Here is where I really doubt the efficiency: Every single function must have Javadoc style comment, and the code is tested by White-box Test automatically. Even when I write simple & short function, the function must have a Javadoc style comment.

For example:

void request_ait(void)
{
      hoa_request_ait();
}

If I write code without a Javadoc style comment, even for this simple function, the QA tool register it as a defect. So I write a simple comment template.

For example:

/**
  * @author peter
  * @version 1.0
  * @since   2011-08-28
  */
    void request_ait(void)
    {
          hoa_request_ait();
    }

I know that comments on API functions or important functions are really useful. But forcing every function to have a Javadoc style comment is inefficient...

I want to listen your opinion.

Am I wrong?

Answer 1

You have probably been reading agile books. The agile style seems to be small functions that do one thing and are well named. In fact within a function if you have to write a comment, many of the agile books advise taking that code, wrapping it in a function with an understandable name which can serve as that comment and calling that. One of the reasons is that they are big into DRY (don't repeat yourself) and comments often have a habit of becoming outdated and repeating stuff that should be clear from the code. The only guaranteed documentation is the code.

But in most real code bases, I often see functions that do multiple things or are poorly named. E.g. request_ait, hoa_request_ait... I have no clue what those functions do. The abbreviations hoa and ait might mean something to your business, but what if someone new comes in? I would say a comment could clear up what is being done (most new people are just thrown into the fire without much formal business training). Many times the acronyms in programs do not tie to common business acronyms. E.g. instead of FindSpellingErrorInList someone decided to do FSE_List or something. Good luck to someone who does not know that FSE is how you find a spelling error in a list unless there is a comment.

Another thing is the language itself. For example Java can document error conditions by throwing well named exception (throws ArgumentOutOfRangeException, throws NoMoreAITSlotsFreeException, etc.). But even then some functions throw runtime exceptions which do not need to be declared and are not obvious. Something like that can benefit from a comment. If you move on to C where errors are often passed by setting errno or returning some type of return value out of the normal range...comments become VERY useful. But if you are going to comment there needs to be stuff in place to keep them up to date, and out of date comments need to be treated as a bug and with the same seriousness as keeping the codebase updated.

Also when using a library in something like Java/Perl often it is much easier just to go through the javadoc/POD [perl documentation format] to read the function names/variable names and a brief description of what they do rather than to go through the code interpreting what is done... I know in both Java and .NET that I do not go through the library source code when I want to use them, I go through the Java Docs/MSDN and that makes me much more productive... Reading the code it is harder to jump file to file from function to function when reading the code. In JavaDocs/MSDN it is really easy to click on the hyper links to jump through the documentation from one function to another.

Additionally comments are the only way to communicate why something is so. The code only communicates what is happening and how it is done (although some declarative languages do not even communicate the how). For the why it requires some other document. E.g. do you need to fire some hardware operations on a device before doing a certain hardware operation? If you do not comment, another developer may look and say hmmm why is this guy/girl doing operation x and then y when they should only be doing y. If you do not document that y does not work unless you do x first with a comment the developer has no way of knowing.

So basically it's a trade off (like most things in software)...... For a function comment the most important things that spring to mind:

1. Are your functions well named with names that clearly reveal what they do? If not, this would seem to indicate comments YAY
2. Do your functions mostly do one thing? If not this would seem to indicate comments....
3. Are there a lot of implicit error conditions, weird out of range return values, numeric error codes (e.g. C errno)? If you answered yes, this would seem to indicate comments
4. Do your functions have many side effects, especially to global structures? If so then comments are your friend.....
5. Is everyone interested in readable code or does the quality of the code base vary based on who works on something? If it varies then comments might be your friend, you don't want to see RLAB

And there are many more things besides those 3. For example, named modules, named classes, named structs, etc. all create a context. If you have a customer class and an attribute called name, then you know that is a customer name. If you just have a variable in the middle of nowhere called name, how do you know if it is a CustomerName, SupplierName, PetName?

To summarize, the most important concern is clearly communicating your intend in the code. If the code does not do that, and you cannot refactor and enforce keeping the code like that then comments are necessary.

That being said, you just moved to this company so you probably will have to conform with the Javadocs whether they are right or wrong.

Answer 2

Setting a strict policy like this helps avoid forgetting comments on functions which are not obvious, or which are obvious only to the person who wrote it. Filling out just enough to silence the automatic warnings is defeating the point; you should be actually putting a useful comment there.

Take your request_ait(), for example. It may be obvious to you what it does, but not to me. What does it do? Why does it just forward to hoa_request_ait()? What's the difference between request_ait() and hoa_request_ait()? Do I need to be holding some kind of lock to call it? What kind of exceptions might it throw? Are there any preconditions I should know about? etc. All of these questions can and should be answered in a good doc comment.

Answer 3

I work at a company where function headers are enforced by the culture (not by QA). They always follow the form ...

/*************************************************************
 *
 * functionName - brief one line summary
 *
 * A more detailed description about what the function is supposed
 * to do.  Usage information is very important and should be added
 * here or under a special CAVEAT section.
 *
 * RETURNS: list the possible return values and what they mean
 *
 * ERRNOS: list the errnos that may be set and their conditions
 */

I've been at this company for close to 10 years and have found function headers for every routine to be extremely useful. They help everyone who has to wander through unfamiliar code, whether they have to review it, use it, track down defects. They even help as reminders and navigation when we know the code; they help in so many ways. Our customers can have access to the source code. These comments help them too. We also generate part of documentation from these comments. Again, they help in so many ways!

With all that in mind, I see your stub comment as not adding value to the code base.

Answer 4

I fully agree with you. A policy that every method must be commented is absolutely horrible, because it only leads to useless, massively duplicated and invariably often outdated or wrong comments that effectively decrease mantainability.

Unfortunately, it is extremely unlikely that as a new hire you can do anything to change this policy. Your best bet may be to discuss it with your colleagues. If they feel like you, you may have a chance to campaign together for the policy to be changed.

Answer 5

Commenting out a function is always a good choice in my opinion.

First and foremost you can actually understand what the function does without having to look deep into the code. This way your code will be easier to understand for other people. You can then need to use less comments for single lines of code, which may result in out of date code (bad documentation is far worse than no documentation at all).

Secondly, you can implement a function contract (see "Design by contract" approach). Design by contract is a good practice that will give you a glance of a function not function properly, not doing what it's supposed to do.

Additionally, a correctly formatted comments can be used to automatically create documentation for all your function in no time, and can be used to track down functions versions and revisions for version-control needs.

You should follow all possible way of having a self-explaining function, starting from the name of the function, to the name of the variables, methods, etc... All these things help other people better understand your code, and help save lot of time in debugging.

Write comments before the function is one of those good practice I advise you to follow.

Answer 6

I don't think efficiency is the issue because you're using a template anyway. Don't waste time deciding which functions should have a comment. Too many teams can get caught up in this debate during code review. It's a battle that's not worth fighting.

Answer 7

Comments are a waste of time. Programmers read source code; any non-coder user-facing documentation should be geared towards exactly that: the user, not the coder reading the code. We as coders aspire to such lofty notions as SRP yet violate it continuously with policies like "comment every method according to this template."

Instead, write the code such that it documents itself. Explanations as to the why belong wherever your general user-facing documentation resides.

Answer 8

I'd probably be annoyed by enforced javadoc-style comments, but that's more because I find all that formatting annoying, and not the comment in and of itself. I generally leave a comment explaining all functions other than getters and setters; I've been bitten too many times by things which were obvious to me when I wrote them being total mysteries when looking at them months later.

For that function the necessity of a comment depends a lot on that term "ait". I mean, I have no idea what that means so a comment would be helpful. On the other hand, perhaps that's a common jargon term in whatever domain you work in.

Answer 9

The problem with these kinds of policies is that they cause developers to use macros in their code editors to add comment templates to all new methods. These comment templates never contain useful information, which defeats the purpose of the policy.

It makes sense to put Javadoc-style comments on public methods, because they will be used by other developers, teams, customers, etc. who aren't familiar with the internals of the codebase. However, putting them on private methods that are only used within a class is overkill, especially if those methods are short and well-named, and the class itself is well-designed.

Answer 10

You might have to stick to the company policy or culture, too bad. But if you ask for opinions ...

Last time, I arrived into a huge project that had that policy. I had to comply, of course. But when I was given responsibility of a new project, I didn't choose the same policy. Every character your write may take some time, but more importantly every character will be read many times in the development activity (by many developers). Each line or character that is not useful is a pollution!

In most projects with a lot of documentation, maintaining it up to date costs a lot of effort (that means money also). Usually comes a time where it is not maintained (due to deadlines, lack of discipline from some people, forget, copy between branches...)(in a perfect world where it wouldn't happen, you might still be paying too much money for it, so it might not be optimal). Then other developers trusting the documentation will try to save time by not checking in the code, have errors and finally, after loosing a good deal of time, find that the documentation was wrong about the code. So after some time nobody trusts the documentation, so every has to go and check directly into the code. So mandatory documentation is useless, and even a liability (in case someone trusts an old documentation and have errors from this).

For these reasons, the documentation should be limited to a strict minimum. As far as one can write an understandable code without documentation, fine. When something requires a comment, then writing such an exceptional documentation item is a warning to all readers of that code, and taken seriously (read, and maintained). This is really useful documentation.

There is a saying that instead of documentating, you should make your code understandable. I agree, and I practice... I delete a lot of documentation in my projects :-)

Still, is there some conditions where you should document? These are my policy:

• Document more the big items (java project, then package, then class, then method, then parameter/return/throw), because as the granularity gets bigger :
  • it covers a bigger portion of your code
  • it changes less often
  • it is more complex
• Document the omissions : when a code is not necessary, there is no code to make this understandable, so the meaning need to be carried by a comment.
• Document the hacks : if you write a hack, it can't be as understandable as the code you would like to write. But why would you write a hack?
  • for performance reasons (after you have proved the performance problem)
  • when using a less than optimal foreign code (you can't modify it)
• Introduction to the functionality : with a few sentences, if you can make your code more understandable to newcomers in that functional area, that's nice. Of course, that probably wouldn't happen on methods, only on higher granularity. And it could be replaced by an external introductory document... But if your developers hate Word as much as mine, javadoc might be a good place for this.
• Introduction to a technique : if you are writing sample code, or a code that will be an inspiration for beginners, explaining (possibly with links) the advanced language features or patterns might make them gain some time. This documentation must not be cut and pasted to other places (that would be pollution), it must remain unique.

Answer 11

You are right. Usually the function name should be enough documentation for short function. But the name should explain what the function does. But if there are more complex functions or a large number of parameters, you should document the function.