How do you document your methods?

Question

As suggested, I have closed the question posed here and have broken it up into separate questions regarding code documentation to be posed throughout the day.

---

The first question I have is, what are the guidelines you follow when you write documentation for a method/function/procedure? Do you always do doc-comments or do you try to let the method names speak for themselves?

What about within the code block? Do you find yourself writing a lot of line by line code? If you do, why do you feel the need for it?

What do you think should be the standard for documenting a small self-contained chunk of code (as opposed to the code as whole or tests)?

Do you find that your opinions differ depending on project size/type? On language you're using? On documentation tools available?

Answer 1

As I said in the now closed post:

I am in general agreement with Steve Yegge that comments on every other line are distracting, unnecessary, and an indicator that the programmer doesn't quite understand the problem domain. That said, if there is a particularly tricky bit of code, the rare self-written algorithm, or any non-trivial nested loops I will put a couple lines explaining it at the top of the code block.

I do not write as many doc comments as I should. I will try to go through and put xml comments (GhostDoc for Visual Studio is a big help for this) on many of my classes and methods but I typically only do this toward the end of the project or if I'm having trouble figuring out what a particular part of my code is supposed to do. Often times, if I deem my method name to be good enough and the method is under 5 lines long I will not bother to comment it.

While I subscribe to the Spartan Programing Principle inside of a method and have plenty of variables named 't' 'ta' and 'v' all input parameters and variables at a higher than local scope are always spelled out so as to not be confusing in intellisense.

One thing I believe to be important, and I think I first heard this view espoused by Joshua Bloch in his mind blowing Google Talk on API design (watch it!), is that doc-comments on public methods should ONLY describe what the method does and maybe why you would need it. It should not say how the method goes about achieving this goal. That would be a leaky abstraction. If you need documentation to describe what you're doing in the method then you should first consider refactoring to private methods, or at the very least, put your explanations within the braces.

Answer 2

I try to make small methods and give a self explaining name.

Answer 3

Method name should be enough documentation in most cases. If you feel a method is so complex that you can't pick a good name describing it all, you should probably refactor to simplify the method. If the method has parameters whose functions are hard to explain with their name, I use a doc comment and document everything at greater length. Also if building a framework or some other library, I will usually doc comment all public methods.

As for the body of the method, I only add comments if the code is hard to understand at first sight, or to explain a multi-step logic that can't easily be splitted.

Answer 4

I make the name of the method say what it does in the context of the object that says what it is (noun-verb),

For example: Person.Eat(food) or George.Read(answer)

If you need more than that there is something wrong with your naming. Also remember that the name of the function is the first thing that you or anyone using your code will see, so make it do most of the work.

Answer 5

The first question I have is, what are the guidelines you follow when you write documentation for a method/function/procedure? Do you always do doc-comments or do you try to let the method names speak for themselves?

I always put comments in the header as soon as I write the function.
-What is does (if the name doesn't make that clear, eg Random())
-Return value
-Pareters, incldueing special cases (null pointers, empty strings)
-What exceptions may be thrown

//Returns a pointer to a texture instance, if the texture is not already loaded, will attempt to load it.
//File Should be a path to the texture file to load, if it is not a full path (eg "c:\example.png") it will attempt to find the file usign the paths provided by the DataSearchPath list
//Return: The pointer to a Texture instance is returned, in the event of an error, an exception is thrown. When you are finished with the texture you chould call the Free() method.
//Exceptions:
//except::FileNotFound
//except::InvalidFile
//except::InvalidParams
//except::CreationFailed
Texture *GetTexture(const std::string &File);

Later on once that component is pretty stable I might write a full doc using the existing comments

What about within the code block? Do you find yourself writing a lot of line by line code? If you do, why do you feel the need for it?

I'm assuming you mean comments, line by line? Not really, I just comment blocks if at all.

//Creates surface, renders to it and saves in working_dir\screenshots

What do you think should be the standard for documenting a small self-contained chunk of code (as opposed to the code as whole or tests)?

Just use a couple of comments. Of course if your going to release it to a wdier audience, more substantial docs may be a good idea.

Do you find that your opinions differ depending on project size/type? On language you're using? On documentation tools available?

I'd say so. When working on a team I'll make sure everything is documented. But when I'm working alone I tend to do little documentation, in favour of making progress (I know what my own code does anyways, so theres little to be gained)

Answer 6

IMHO variable or function naming should be descriptive and tell you what that thing does or is for.

Comments should be restricted to telling you why something is being done, i.e. it should not be needed very often, but perhaps when you choose to do something in a non-intuitive manner, i.e. for performance gains, or as a workaround to a problem.

Answer 7

I think it was The Pragmatic Programmer that suggested to focus on comments for methods/functions. Your code blocks should be as self-documenting as possible, with help of variable names, submethods with meaningful names and the occasional comment.

For methods, input and output (not just int, double, but what it represents, or even the range of values), and what it does, not how. Comments on possible side-effects or your function are nice too. How is usually not relevant, unless you use some specific algorithm and want to indicate why, like why you use DFS instead of BFS for some graph related problem.

As for tools, one useful thing is including type information in dynamic languages, because it is not always clear, and it helps to have it documented.

Answer 8

For method level doc comments, it is all about the what questions: what are the inputs, what are the returns, what can I expect it to do, what are the side effects, what can it throw.

Within methods, comments should only be used to answer why questions. If you need comments within a method that describe what is happening, your code needs to be refactored.

Answer 9

Hey George,

I try to create methods and parameter names that are useful to the user of the method. I prefer to less documentation rather than more but if I think it is at all confusing, I'll add some commentary to make it clear to the user. Nothing I hate more than undocumented libraries where it is unclear, for example, what units a method expects.

I put it in there only for two reasons: First, to convey TODO's - which are removed later when I do them. Second, to clarify why I chose do implement the method that way. I don't write 'clever' code so I don't feel the need to 'teach' within my methods. The assumption is the reader knows the language, but might not know (or remember!) why a particular choice was made.

I think the standard should be that one of my team members (who didn't write the code) can tell what it does and what it expects as input and what it will spit out. It if isn't clear, it needs a comment. But comments should be used like salt - sparingly.

I'm far more likely to comment if the tool provides a means to stub out the comment.

My two cents, anyhow.

Answer 10

The first question I have is, what are the guidelines you follow when you write documentation for a method/function/procedure? Do you always do doc-comments or do you try to let the method names speak for themselves?

My first goal is always name the methods so anyone can understand what they are supposed to do at first glance. Even though some doc-comments on the method header are a nice addiction, I find it's always better to know what's going on at your code by reading it. Having to search the docs - even by mouse hover - is not as fast as just reading it. I always try to add extra info on the doc-comments, like conditions for each thrown exception and the return type - if I find it's not obvious by reading the method name.

What about within the code block? Do you find yourself writing a lot of line by line code? If you do, why do you feel the need for it?

More often than not, if I find a piece of code that's worth commenting, then it's probably either needless complicated and/or it can/should be extracted into a method of its own. I like to encapsulate minimal functionality on methods, so it's easier to unit test them and make the rest of your code easier to read and understand. Almost every time, the newly created method's name says more than an inline comment, and now you need only to read it out loud to understand what's going on on that part of the code.

What do you think should be the standard for documenting a small self-contained chunk of code (as opposed to the code as whole or tests)?

Like the code itself, documentation should be also small, but meaningful. I like to keep it brief, document unexpected situations (exceptions) and - if necessary - the return value (if any).

Do you find that your opinions differ depending on project size/type? On language you're using? On documentation tools available?

It's not about the project size, the language I'm using or the doc tools available. I only think an extensive code documentation is valid if you're creating an API that will be used by other developers (of-the-shell components, enterprise libraries and so on), so they can understand the interfaces/methods you're providing without having to hack through your code.

Answer 11

I write big documentation for the class itself which describes the rationale of it, 30% describing what it does and 50% how it is done, 20% describing some preconditions, postconditions and invariants that possibly may hold.

Methods that are more than 10 lines containing documentation describing why (70%) and how (30%).

Writing the docs describing what code does is pointless since code talks itself, but I haven't seen code describing why it does what it does.