When do you start documenting the code?

Question

Some friends and I recently started a medium-size project. We already covered the design part (at least the first attempt) and now we are moving into coding. We already have implemented some objects of the design, just to test if everything is going as expected (we are beginners, so we do not really trust our programming skills).

The project is growing really fast but I do not really know when to start documenting the code. If I do it too soon the code will probably change, and so the documentation.

Is there any "golden rule" for when to start documenting the code? Is there any time which is optimal to start? or it just does not matter?

Thanks!

EDIT: I changed "commenting" to "documenting" because I realized it is not the same. Sorry.

---

ANSWER

Thank you all for your contributions. I'll try to post here the solution I got from reading all your answers.

When do you start commenting?

• Comment the code as you write it because...

  1. you wont come back later to comment
  2. it will never be clearer in your mind

• Document the API. Create a design document separated from the original code and/or comment the header of your interfaces so:

  1. It gets everyone in the same page
  2. It helps everyone stay in the same page (no unwanted morphing)
  3. It can evolve in the future into a more elaborated document

I selected @Octávio answer as the right one because it hit an important fact: comment before it is too late.

Thank you all again for your insightful answers!

Answer 1

If you don't comment the code as you write it chances are minimal that you will come back and do it later (let alone do it properly).

Answer 2

Comment the code when you have something of note that needs to be recorded and isn't readily evident in the code itself. You don't really need to comment everything, but if you have something unintuitive that needs to be explained then that deserves a comment. A common example of this is the use of a "magic number." If the code uses a value that means something (maybe adding some numeric value to an existing variable) then you'd want to note in a comment what that value means and why it's there.

Comments can also be useful for adding metadata to an API. So if your team is abstracting components behind testable interfaces then you'd want to comment those interfaces with API descriptive comments so that the team can effectively communicate the purposes of the code. The implementations of the interfaces aren't as important, since those can change easily and often. But the interfaces represent a common domain language, which requires more information to maintain an understanding of the problem domain.

Answer 3

We already covered the design part

If that's true, then you've probably already started documenting your code. A design document is one of the most important documents because:

• it gets everyone (developers, customer, managers) on the same page

• it'll help everyone stay on the same page -- design goals have a way of morphing in different directions, leading to misunderstandings, unless they're written down

• it can evolve into other parts of the project documentation

The specificity of the design document will vary depending on how well the design goals are understood at the outset, the relationship between developers and customer, and other factors. Often, the design document has to be very detailed and requires customer approval before any implementation starts. In such cases, if the design is done very well, there may not be much more documentation that has to be done as the project proceeds. Other times, the problem space may not be understood well enough to do a very detailed design, and in such cases more documenting needs to happen as the implementation proceeds. Even so, you should be able to write down some sort of synopsis of a class, method, function, or structure before you jump into coding it up.

Documentation is traditionally something that developers hate to do, but I think a big part of that comes from waiting until the entire system is built and then trying to document it afterward. If you instead do it a little at a time in some format (wiki) that's easy to update as needed, it's not such a burden.

Answer 4

Personally, I comment the code as I work so that I can always recall what I was doing or so that if I'm hit by a bus the next guy can figure it out. As far as more exportable documentation goes, I tend to write it in a couple of goes... I write the initial documentation from my expectations (or spec) and revise it after I've finished testing the code.

I also use Doxygen to help make my documentation "on demand" with the final product being a hand tuned document.

Answer 5

There are two reasons to comment code:

1) So others can understand what you did.

2) So you can understand what you did.

If I'm writing something for myself, I tend to clean up and document around the third or fourth time I touch the code. That's when it's more than a simple script and becoming something I need to keep track of and may push out to others.

If I'm writing for others, I'm documenting from the beginning. In those cases, I may have external rules for how I must document. If not, readable code is preferable to readable documentation - descriptive names, clear code block structures, modular functions/objects/classes. Documenting on a higher level (blocks, objects, classes) is REALLY useful for the person who is jumping into your code and doesn't know where to start or have much detail of what your code is doing.

I disagree with documenting what vs why vs how - what you think is obvious may not be to the next geek. There is a fine balance in handling "Should I explain how a wheel works?" In general, coding for clarity helps with this. If your call is complex, a one-line explanation is sufficient. Always consider that the person using or maintaining your code may not have the context you do - experience, training, perspective.

And context is where it all lay - if it's a function that everyone on the team knows forward and backwards, documenting it is likely useless work, while your time would be better spent documenting that neat algorithm you found in a book.

Answer 6

As far as documenting the code goes, I would say once you are sure the portion you are documenting will not change (or if it does only in some minimal way as to not require a total rewrite). Determining when this point has been reached is entirely up to you, your teammates, and your knowledge of the code base.

If you have written a specification for the project and you have implemented a specific functionality, document it before starting on a new part of the project. The code you just worked on will be fresh in your mind and this can also help you go over the code in your head which can help you spot possible mistakes, areas for improvement, or just something you didn't see before.

Answer 7

I start to document my personal code once I can no longer keep it straight. If I can't remember something I go figure it out again and then make sure the comments and docstrings explain what it does.

If you are writing code with multiple people than you should document what the code does before it is written so that you can make sure it fits together and that what is written fits the design goals.

Answer 8

You should keep external documentation of the code to a minimum. A simple guide to the directory structure should be enough. If the source code is not readily understandable, then improve it. If you are using some framework, then some pointers to the documentation for those frameworks would be nice.

You should also document any manual processes needed to work on the software, e.g. the installation of any software your application depends on that must be installed before work can begin.

I am very fond of Wikis for this sort of documentation.

Answer 9

I always use this rule of thumb:

"Don't put a comment to say what you're doing. I can read code...I can see what you're doing. What I want to know, is why on earth you're doing it!.

Answer 10

Start documenting it when the time savings obtained by documenting code are greater than the time spent documenting it.

Considering the effort required to write documentation it's usually advisable to keep the code simple so that that point is never reached.

Note: This answer answers your second question where you ask when to document - rather than comment - it. Try not to edit your question completely changing meaning or it will make all the other answers obsolete.

Answer 11

I would say...

Document the project - app flow is becoming more important with mobile devices these days. Document that app flow first. I just started using www.iplotz.com, and I like it as a way to provide a graphical prototype for a new app. Lets me get feedback from the customer. Document that as the project progresses.

Comment the code as needed to help a maintenance programmer know what the purpose is if it isn't easy to understand.

Document the code if you get into doing many special functions that are called throughout the app, and which a new programmer would need to know about to get going with things. Document those common callable aspects so a new developer knows what is available and doesn't instead re-invent wheels the developers have already handled.

Greg

Answer 12

I remember an approach mentioned in "Code Complete". If you are writing a function, write it in simple language what this function is supposed to do, before even writing the code. I follow this approach and it has been useful for making me write better code. Other place where comments are needed is you know you are doing something complex and you wont remember afterwards why you done like this, comment it.

Answer 13

I start to document my code just before my peers start complaining that they don't understand it.

A skill that is very hard to master and that I've yet have to master.