Sign up ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free.

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?


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


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!


migration rejected from Oct 19 at 14:53

This question came from our site for professional and enthusiast programmers. Votes, comments, and answers are locked due to the question being closed here, but it may be eligible for editing and reopening on the site where it originated.

closed as too broad by MichaelT, Ixrec, gnat, durron597, Snowman Oct 19 at 14:53

There are either too many possible answers, or good answers would be too long for this format. Please add details to narrow the answer set or to isolate an issue that can be answered in a few paragraphs.If this question can be reworded to fit the rules in the help center, please edit the question.

Once it works, I have extra time, and when the StyleCop starts yelling at me. – Job Aug 7 '11 at 19:07
You know that "documenting the code" mean "explain the things not self-evident from the code"? – user1249 Aug 7 '11 at 20:34
@Thorbjørn: I wanted to differentiate the "commenting this part of code method because it's tricky and I do not want to forget" case (what I understood as comment) from the "commenting the interface of this class to have a further reference when using it" case (what I understood as documenting). Now I realize I was not clear from the begining, sorry. – Alejandro Cámara Aug 7 '11 at 21:52
@Alejandro. There is a trend of writing code to be as clear as possible without needing comments to say how things are done (because those comments violate DRY). You should keep comments to why things are as they are. If they say "how" then refactor so they are not needed anymore. – user1249 Aug 7 '11 at 21:56

11 Answers 11

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.

</zen guru meditation> – Spoike Aug 8 '11 at 6:50

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.


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.


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, 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.



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!.


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.


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.


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.

+1, although I'd say it's even better if you can start documenting just before you have to figure things out again. :) – Steven Aug 8 '11 at 1:10

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.


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.

design document +1. It helps to have a nice over view of how you were expecting the system to develop. Even if it is different – nelaar Aug 8 '11 at 10:03
In the context of documenting-as-you-go in some format (wiki), I'll parrot others in saying that wiki-code, LaTeX, or other documentation-markup should be committed to source-repositories so that it can be versioned right along with the source itself; when using separate blogs or wikis, it's easy to forget to include the precise version-number and/or commit hash that a given revision applies to. However, this is not an issue if the docs are kept up and committed right along with the rest of the code. – SeldomNeedy Oct 25 at 4:01

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.


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