Should a function's comment include descriptions of work done by functions it calls?

Question

Let's say I have a function called DisplayWhiskers() which puts some slashes and backslashes on the screen to represent an animal's whiskers like this: /// \\\. I might write a comment for this function along the lines of

// Represents an animal's whiskers by displaying three  
// slashes followed by a space and three backslashes

But if I then add functions DisplayKitten() and DisplaySealion() which as part of their work call DisplayWhiskers(), how much detail about the displaying of whiskers should go in the comments for these other functions?

On one hand, it seems that I should be able to look at the comments for DisplayKitten() and understand everything I need to about what it's going to do, including exactly how it will display the whiskers. I shouldn't have to go elsewhere to read the comments for DisplayWhiskers() to find this out.

On the other hand, if the comments for DisplayKitten() explicitly refer to three slashes followed by three backslashes, this seems to go against the spirit of encapsulation and could become erroneous if DisplayWhiskers() is later changed.

What is considered best practice?

EDIT: Several answers have suggested that the solution is to read the code. I understand the principle of good code being its own best comment, but for this question I didn't mean to refer to in-code comments, but to the comments in header files that accompany the function prototypes. Let's assume the actual code is pre-compiled and not accessible to the client who wants to use or call it.

Answer 1

You seem to be naming your functions descriptive enough and leaving them to do only one thing (single responsibility). By reading the code you would essentially understand what they are doing. This would be my preference instead of adding comments.

Answer 2

Normally I wouldn't mention all the work done by all the subroutines. It could get very tedious. It might be worth mentioning if one of the subroutines does something unusual, or has interesting side effects that would otherwise be unknown.

Answer 3

I would say that you should write your code clearly and name it appropriately so that it is self-documenting and doesn't need comments for future programmers to understand what it does. Then you would only use comments to document API functions (where the user doesn't have access to the code base) or complex/non-obvious things that you haven't been able to refactor to make them more understandable.

Answer 4

I'd argue that in general, this paragraph is on the right track for 99% of cases:

On the other hand, if the comments for DisplayKitten() explicitly refer to three slashes followed by three backslashes, this seems to go against the spirit of encapsulation and could become erroneous if DisplayWhiskers() is later changed.

How DisplayKitten() calls DisplayWhiskers(), and even the fact that it calls it, is probably an implementation detail.

There are cases where this is not true. Sometimes you have a "convenience function" whose job is to just call another function in a particular way. In those cases it may make sense to intentionally break the encapsulation in your documentation. These cases are the exception to the rule, however.

Answer 5

Your functions should ideally do one thing only, whatever a "thing" may be and at what level of granularity.

Similarly, they should be described at the appropriate level of granularity. If you're printing out an ASCII kitten, you can leave that as the description for DisplayKitten(). You don't have to describe every last thing it does.

Think about it. If every function described every last thing it did, your main function would have to describe every individual thing anything in the program would do, and that's way overkill. Moreover, most of that comment would be distributed among the called functions, and so on, so the program would wind up as mostly ridiculously detailed comments.

So, leave the comments to what the function does in general, and as long as your function names are sufficiently descriptive (and yours are) cut those to a minimum. If you or your users need more detail, they can examine the code.

Answer 6

keep the comments DRY

Answer 7

In general, comments should not concentrate on what the code does -- the code itself documents that. Instead they should concentrate on WHY things are being done.

Answer 8

"for this question I didn't mean to refer to in-code comments, but to the comments in header files that accompany the function prototypes."

You'd probably get different answers if you replace the word "comments" with the word "documentation" throughout your question. I think this addition changes the question quite a lot.

There's a huge difference between an interface that you're committed to, and a few notes about how your implementation happens to accomplish something. You should take the former very seriously, and make sure it contains everything the caller needs to know, and no more. The latter should be kept as far away from callers as possible, so that if you want to change it in future, you can do so without affecting any other code.

In this case, kittens clearly have whiskers, so that much should be documented. But is it a vital feature of kittens that they have three whiskers on each side? I don't know, it depends entirely on the real problem domain, and the design of your code. If not, you probably shouldn't be documenting it, and perhaps should specifically mention that the number of whiskers may change without warning in future.

Answer 9

Method comments (ideally in javadoc form, despite its hideous syntax) should accompany methods, and should include what a caller needs to know to call the method, and nothing else (except possibly what a subclasser needs to know).

What work is done by submethods is an implementation detail. Indeed, whether there even are any submethods is an implementation detail.

Just tell potential callers what they need to know, things like: does displayKitten() actually display a kitten? If so, where? Or does it return a string representation?

Should you give the format? That depends. Is the actual representation of a kitten an implementation detail, as described in the question? In that case, no, you should not give the format. But if it's in compliance with some specification, it's good practice to reference the spec - possibly even in the method name: displayKittenPerFsda246_a().