Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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?

share|improve this question

migrated from stackoverflow.com Aug 28 '11 at 11:47

This question came from our site for professional and enthusiast programmers.

5  
At least you have automated tools ... can't you just script your IDE to auto-insert these for you as you type /**? –  Job Aug 28 '11 at 13:30
1  
Are you saying that you write code without comments ;-) Seriously, with today's IDE and complex architecture, every comments help and will be quite easy to put in. –  tehnyit Aug 29 '11 at 6:26
9  
Even that simple function needs a comment: what is its purpose? Why create a function just to call another one? Wouldn't it be simpler to directly call hoa_request_ait() and remove request_ait()? Why does this function exist? To me a comment is necessary. –  mouviciel Aug 29 '11 at 12:56
1  
this is a terrible straw man, your function names don't document themselves at all, request_ait doesn't mean anything to anyone that doesn't already know what ait should mean. In this case, yes a comment on what you are doing should be required, if you can't name your methods more discriptively. Normally I would say less comments are better, it should force you to name methods more intuitively, but your example I have to go with to mancy comments instead of to few. –  Jarrod Roberson Sep 21 '11 at 0:19
    
oya, thank you all. some guys say that I should follow the rules. and others say that the agree with me, and the function name should describe itself. –  sunglim Sep 23 '11 at 7:54

11 Answers 11

up vote 8 down vote accepted

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.

share|improve this answer

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.

share|improve this answer
4  
At some point, someone will notice the half-baked comments and adjust the QA tool to begin choking on them. Then he'll get a nastygram from management about it and spend a few very boring days doing nothing but writing comments. –  Blrfl Aug 28 '11 at 14:24
2  
This kind of thinking leads to 10 lines of comments for 1 line of code, which really is horribly inefficient and reduces maintainability because the comments will on average be worse than useless. –  Michael Borgwardt Aug 29 '11 at 8:11
2  
Nobody's saying there has to be a high comment-to-code ratio, just that there should be a description of every function/method/whatever. One-liners are pathological cases, but if you want to get strict and OOP-y about it, the length of the function is an implementation detail that shouldn't make any difference how things look from the outside. –  Blrfl Aug 29 '11 at 12:13

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.

share|improve this answer
7  
One day, someone's going to rake him over the coals for having written so many functions with no useful documentation, and becuase his stub comments basically only tell you his name, they'll know exactly who's at fault for failure to document these functions. –  Ken Bloom Aug 28 '11 at 14:26
    
How do you deal with duplication of comments (in case of methods that forward calls)? How with comments that lie (because they became outdated, perhaps in combination with duplication, or were copy/pasted)? –  Michael Borgwardt Aug 29 '11 at 8:14
1  
@Michael: Duplication can be dealt with via a module description comment, adding reference notes, or even indicating the routine is a wrapper where appropriate. There is nothing wrong with documentation that says "Please refer to xxx for more information". Comments that do not match the code (for any reason) do not add value to your project--they detract value and mean that source code (of which comments are a subset) is wrong and must be corrected (file a defect, track it, and get it fixed). –  Sparky Aug 29 '11 at 11:11
1  
@Sparky: or you could save yourself the make-work and just not have comments for trivial methods. –  Michael Borgwardt Aug 29 '11 at 11:24
2  
@Ken Bloom: Easily solved. Just use someone else's name. –  Dave Sherohman Aug 29 '11 at 11:42

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.

share|improve this answer

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.

share|improve this answer
2  
IMO it is very much worth fighting. Excessive comments decrease maintainablity. –  Michael Borgwardt Aug 29 '11 at 8:17
    
"Excessive comments decrease maintainablity" the right amount of comments in the right place increase it. –  Jose Faeti Aug 29 '11 at 12:54
2  
@Jose Agreed, but mandating comments everywhere is not the way to have the right amount of comments in the right place. –  Adam Jaskiewicz Aug 29 '11 at 15:13

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.

share|improve this answer
    
+1 short ; two meaningful paragraphs for two ideas ;-) –  KLE Aug 29 '11 at 15:30

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.

share|improve this answer

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.

share|improve this answer

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.

share|improve this answer

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.
share|improve this answer

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.

share|improve this answer
2  
-1: What's obvious to you might not be obvious to others. Also, writing the JavaDoc will make the function appear in generated documentation. –  Lstor Aug 28 '11 at 13:09
2  
+1 If the code is written well, and the method small enough then it should be simple enough to understand without a comment that requires ongoing maintenance, and adds noise to the code. Comments are necessary sometimes, but making them mandatory is counter-productive. –  Ben Aug 28 '11 at 13:32
4  
+1. Countless times I've seen documentation such as "initializes the object" for a method named initialize. Such comments introduce no value, only clutter and noise and thereby make code harder to read. –  back2dos Aug 28 '11 at 15:36
1  
@back2dos: bad documentation is worse than no documentation at all, that's for sure. But if used well, a comment on top of a function can be of invaluable help. –  Jose Faeti Aug 28 '11 at 17:21
3  
@Jose Faeti: Show one occurrence of the word "comment" in the explanation of design by contract. Also, all I need to know about a function is, what it is supposed to do. I don't care how. I suggest you read about encapsulation in case of doubt. Comments are not meant to provide the how but the why. Code already provides the how. If it doesn't the code is poor and slapping a comment on it won't improve it. Comments are a code smell, full stop. –  back2dos Aug 29 '11 at 10:48

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.