Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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!

share|improve this question
1  
Once it works, I have extra time, and when the StyleCop starts yelling at me. –  Job Aug 7 '11 at 19:07
3  
You know that "documenting the code" mean "explain the things not self-evident from the code"? –  user1249 Aug 7 '11 at 20:34
1  
@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
5  
@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
add comment

migrated from stackoverflow.com Aug 7 '11 at 18:53

This question came from our site for professional and enthusiast programmers.

13 Answers

up vote 36 down vote accepted

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

share|improve this answer
4  
I'd add that if you're willing to change the code, you should be willing to change the documentation. –  Matthew Flynn Aug 7 '11 at 21:24
5  
Also, it will never be clearer in your mind than when you've just written it. In other words, it will take the least effort to do it then. –  user1249 Aug 7 '11 at 21:57
3  
If you develop using stubs, document what the stubs (will) do when you create them. What the stub does shouldn't change much. Avoid documenting how the stub will work (that should be obvious once it is implemented), as the implementation is likely to change. –  BillThor Aug 7 '11 at 22:07
1  
As much as I believe that this answer is good advice, it's not true in my case: I frequently document code before I hand it off. –  Fixee Aug 7 '11 at 23:34
3  
He does say why - because its unlikely they'd go back and document. I think thats probably an accurate assessment for most projects. Its less dull to document as you code. –  GrandmasterB Aug 8 '11 at 3:44
show 1 more comment

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.

share|improve this answer
    
</zen guru meditation> –  Spoike Aug 8 '11 at 6:50
add comment

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.

share|improve this answer
add comment

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.

share|improve this answer
add comment

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

share|improve this answer
add comment

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

share|improve this answer
add comment

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.

share|improve this answer
add comment

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.

share|improve this answer
add comment

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.

share|improve this answer
    
+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
add comment

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.

share|improve this answer
add comment

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.

share|improve this answer
    
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
add comment

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.

share|improve this answer
add comment

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.

share|improve this answer
2  
"If the code uses a value that means something … then you'd want to note in a comment what that value means and why it's there" or give the value a meaningful name in the code. –  user4051 Aug 7 '11 at 18:59
1  
@Graham Lee: True. But many times a meaningful name isn't enough. A short paragraph can be warranted to explain why something is happening a specific way. The code may very well express what it's doing, the names may very well express all the players, but if the deeper meaning isn't captured then a comment is most definitely warranted. –  David Aug 7 '11 at 19:12
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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