Commenting Code to "Ramp Up"

Question

I've just started at a new job. My manager and mentor suggested that I ramp up to the code base by documenting the code in comments. He intends for me to check in the documentation that I write, I believe.

The writers of the code have left me a blank slate; there are only a few inline comments in really crucial places. I find that the code is otherwise well-written, and I've gotten a great introductory lecture to the architecture which maps rather neatly to what I see.

What's a good strategy to go about documenting this code for my own education?

• Should I break up my documentation work by module?
• Should I start high and work down?
• Should I be more exhaustive, or should I make more rapid progress?
• Should I concentrate on imperative modules (e.g. class server_thread) or tight objects (e.g. class packet_buffer)?
• ... ?

Answer 1

There are many styles, but I personally find it very helpful to have one comment per class (describing the class in general terms), and one comment per method, which lists input parameters, result, and any pre- and post-conditions of the method.

I would recommend you use some template system. In Java that would be Javadoc, in C++ et. al something like Doxygen. That way, your comments can be automatically parsed, formatted as separate documentation or extracted by the IDE, and checked for completeness / consistency (e.g. undocumented parameters).

As a bonus, there are checkes available (e.g. built into Eclipse) that will highlight incomplete/missing docs.

If you have complete coverage of such docs, then you have a very well documented codebase.

As to inline comments, I would use them very sparingly (if at all). The rule of thumb is: If you need inline comments, then your code is too complicated, or your method is too long.

The only exception I can think of is code that is impossible to understand without knowledge external to the code. Examples would be implementation of complex mathematical algorithms, tax calculations, internal business rules, or non-obvious workarounds for bugs in a system you need to interface with.

Even in these cases, inline comments should be few and brief. If that is not enough, refer to external documentation for things like algorithm details.

As to where to start: It does not really matter. Usually a combination of top-down and bottom-up makes most sense. Ask around which part people feel is most in need of documentation (or which was the source of most bugs recently). If there is nothing to guide you, just pick something.

The same goes for being exhaustive or not. You can start by just writing class comments (less exhaustive), or completely do one class with all methods (more thorough). Decide based on criteria above.

Answer 2

What's a good strategy to go about documenting this code for my own education?

1. Ask for a real to-do item, that will require you to change the code (e.g. a bug fix or a new feature), as well as or instead of writing documentation
2. Understand/learn whatever you need to, in order to implement that to-do item
3. Record/document whatever you happened/needed to learn while doing that (but focus on the to-do item)

(If you were doing it for someone else's education then I'd recommend a different strategy.)

I also recommend that you document the data (e.g. member data, local data, parameters, global data, input and output data) more than the code.

Answer 3

First, make sure your mentor wants you to commit your commented source. I suspect he or she wants you to comment the code to gain understanding and then transfer the knowledge to a formal document, after which you'll remove the comments. The reason is too many comments are worse than too little. Ideally we want to write self documenting code, which does not need comments, although I rarely see it in practice.

I like to create documents that walk the reader through it like he or she is sitting next to me at my computer. Break the document up into sections, like UI and Business Logic. Then document every class under those sections. Don't repeat the code, but give an overview of it's purpose and call out anything that might trip someone up or that took you awhile to find or understand, such as sub classes. Sub classes hide inside another class and can't be seen just from scanning down the Solution Explorer(Visual Studio). What are the most used methods? What methods seem to get the most maintenance? Write it so a new person can walk in, read through the document and actually go fix something without spending half the day trying to figure out what does what or where to start at.

In the end, if the team doesn't have a template then do what you're comfortable with. You're breaking new ground, enjoy it!

Answer 4

If you are going to comment may I recommend the following ...

• Module Descriptions
  • A section on how it is meant to be used
  • Another section on how it is meant to fit into the larger picture
  • Another section for internal implementation details
• Function Descriptions
  • A one line summary
  • A more detailed description if warranted
  • What does it return and what are its errors
  • An indication if this is a public/internal/helper API.
  • If a helper, which routine(s) does it help.
• Inside the functions / routines
  • What the code is supposed to do
  • Note any known gotchas with respect to other modules

Best of luck.

Answer 5

Given that you're new to the job and you already said that with the "great introductory lecture" it maps nicely to what you see and the code sounds nicely self-documenting. So maybe just record your "great introductory lecture" (probably including data model details and input/output specifications would be useful) and you'll be good to move on and not waste your time... [Unless your bosses specifically want more code comments to satisfy some auditor's inane checklist, in which case get familiar with a pretty doc generator.]

The rest you can comment as you go along with specific tasks. That is, only if something in particular is confusing/requires more back knowledge (for which you've happened to discover the answer)... I would challenge you to actually even be able to write good/relevant comments on code you're just reading as opposed to writing.