Does your company require documentation? If so, what kind?

[Frankey James]

I don't want to hear if you program at home orhobby. I'm talking about working in a professional environment.

Does your employer require documentation? What kind? Who does this? Do you use JavaDocs? If you are an MS programmer, what do you do to document code.


I'd like to see what goes on in other shops. My boss/lead programmer seems to think commenting code is something you only do in college and makes his point by saying 'you don't need to document every line'. The reality is that almost no lines of code are documented and I find this rather annoying and unprofessional. I've always liked JavaDcos and commenting code/inline comments.

What says you?

[Rob Spoor]

My company doesn't require any comments in code, but I always write Javadoc for every class, method and field, whether they are private or not. If not for someone else, then for me weeks or months later.

Also, I write comments inside methods where I see them necessary. Sometimes as a reminder for what conditions are true (especially with multiple if statements*), sometimes because a block is a bit hard to understand. But if the code is straightforward I don't comment.


* for example:

if (condition1)
{
    ...
    return;
}
// !condition1
if (condition2)
{
    ...
    return;
}
// !condition1 && !condition2
...

Not really necessary, but it helps me keep an overview.

[Jesper de Jong]

I do projects for different clients, and what and how we document is different from client to client. One documentation standard that I've come across more than once is MIL-STD-498. It's a specification of different kinds of documents that different people write during the course of a software development project. This is not about JavaDoc comments or other documentation in the source code.

For JavaDoc comments, it also depends. In my current project, we more or less have agreed that all public classes, interfaces and methods have to have JavaDoc comments, but more often than not the comments are lacking or aren't updated if changes are made to the software. In my opinion, obsolete comments are even worse than no comments, because they can mislead the programmer who reads them.

You have to think about writing good comments in the source code. I agree that commenting every line is not useful. Comments should express the intent, or the idea behind the code. Comments that just say what the code does are useless. Some quick examples of bad comments would be:

// Increment the counter
counter++;

// Loop through the list of names
for (String name : names) {
    // ...
}

// Sort the list of names
Collections.sort(names);

I consider those bad comments because what the code below them does is quite obvious; the comments just tell you what the code does, which you can just as easily see by looking at the code itself.

Some more on this:
Code Tells You How, Comments Tell You Why
When Good Comments Go Bad
Common Excuses Used To Comment Code and What To Do About Them
Portrait of a N00b

[Frankey James]

Jesper, in the first link you provide they have a cod sample:

You may very well know that 
$string = join('',reverse(split('',$string))); 

reverses your string, but how hard is it to insert 

# Reverse the string 

into your Perl file? 

  

and then the author says "Indeed. It's not hard at all. Code can only tell you how the program works; comments can tell you why it works. Try not to shortchange your fellow developers in either area "

This I absolutely agree with! We dont' have comments on methods, class declerations, tricky blocks inside mehtods - just nearly nothing. My lead went to school as an EE and aside from some c it's my understanding he didn't take any traditional CS courses. Now I know it's not practical to comment every line like they want in class, but I find not commenting at all or almost at all unprofessional. Furthermore, JavaDocs provide documentation after all the code is done. WE won't have any sort of thing like this. What's worse, is we don't have any pre-documentation either. It's just a hack n' go sort of thing if you ask me. This is my first job as a programmer, but in a limited fashion I've worked iwth other programmers at other companies and their code usually had comments in them. So, this is why ask what others are doing.

Anyways, that's my rant. I guess I just think I shouldn't have to figure something out that someone else already has. At least not completely all over again. It's just a waste of company money in my opinion.

[John de Michele]

Frankey,

I would argue that in your second example, the method should have been named reverse() or reverseString(). Then you wouldn't need a separate comment on what the code is doing. That's what is called self-documenting code.

As for my documentation, my work doesn't have rules requiring me to document my code. However, since I actually want other people to be able to use it, I always use a combination of javadocs and self-documenting code. I very rarely use internal comments, because I try to make my code as clear as possible so that someone who is familiar with the language I'm coding in, or even a reasonably experienced programmer who doesn't know the language, would know what was going on.

John.

[Frankey James]

John de Michele wrote:Frankey,

I would argue that in your second example, the method should have been named reverse() or reverseString(). Then you wouldn't need a separate comment on what the code is doing. That's what is called self-documenting code.

As for my documentation, my work doesn't have rules requiring me to document my code. However, since I actually want other people to be able to use it, I always use a combination of javadocs and self-documenting code. I very rarely use internal comments, because I try to make my code as clear as possible so that someone who is familiar with the language I'm coding in, or even a reasonably experienced programmer who doesn't know the language, would know what was going on.

John.

That code is not mine. It's from the first link Jesper provided. Still, I see your point. I think the author was just using that as a quick and dirty example to show that in situations that aren't obvious a little tip for your fellow human can go a long way.

'self-documenting'...I like that. By internal comments, do you mean internal to a mehtod or to a class? The latter meaning you rarely comment your code? What if your code is partially implemented and the 'other' person is to fnish the business. Do you still have JavaDocs for that, or do you do the JavaDocs when you think are done with the code?

[John de Michele]

Frankey:

Internal to a method. Each method should have its own javadoc describing what it does, without giving away the implementation. I generally prefer to either complete my work on a method, or leave it entirely for another coder. If I had to leave it partially finished, I would put in a FIXME comment, with a small note describing what I was doing and what needed to be done. The expectation would be that the comment would be eliminated once the code was fixed.

John.

[Joe Ess]

I maintain a pretty large (100,000+ line) application, so documentation is very important. Nobody could remember how everything works and why changes were made. Documentation means not just documenting the code, but also documenting the system. We use a wiki to document how the system should work, how to set up a workstation (so we all have the same environment in case someone needs a hand), what to do when the system goes wrong and so on. If you are following a procedure in the wiki and you find an error, it's up to you to fix it. This keeps our documentation a living document (as opposed to printed documentation, which ages fast) and keeps our procedures from being tribal knowledge, which can be easily lost.
We also use bugzilla to keep track of feature requests, bugs and enhancements. Everything that goes into version control is associated with a bug number so when you see a change has been made, you can find out why that change was made. Often, when I'm changing something in the code, I'll just comment that one should "look at bug XXX" for an explanation as to why I made a change.
Finally, in all my smaller projects (I have about a dozen), I put a README file in the root directory of the source control module. This will include instructions on how to set the build environment, how to build the project, how to deploy the application and any other developer notes I think I'll need to know in 6 months time. I've made this a consistent practice so I always know exactly where to go to get my project up and running after an absence.

[steve souza]

I think the more your code is object oriented code the more important it is to document. Object oriented code isn't as linear as standard structural code and often you can dynamically assemble your objects in different ways at runtime. Think of a class with a method called 'execute()'. It is left up to the implementing class to determine what that means. This often hides the intent of the code, and so makes it hard to understand. Multiple this by many interfaces and base classes in a framework and things quickly become difficult to understand.

As the other posters in this thread mention, your comments should speak to intent (i.e. things that the user can't get from looking at the code).

Also, with my own code I have found that my most documented code is often the most poorly designed and buggy. In this case I end up documenting all the gotchas to add clarity to my disorganized design. Every once in a while I go through my code and look for the most commented sections and see if I can clean up the design. "Code Complete" is a phenomenal book and it discusses good code at many levels including comments.

http://www.amazon.com/Code-Complete-Practical-Handbook-Construction/dp/0735619670/ref=sr_1_1?ie=UTF8&s=books&qid=1241188890&sr=1-1

Also package.html is a great place to tie the overall design of your package together and talk about the overall design and how the Classes interact. I think this is an underused part of the javadocs.

[Cameron Wallace McKenzie]

Jesper provided some good links.

I always comment the 'why.' There were too many times my Junior programming days where I went back to code and thought 'what was I thinking?!?' When you do that to your own code, you can only imagine how defeated another person maintaining it might feel.

-Cameron McKenzie

[John de Michele]

Cameron:

I guess that's a "junior moment" rather than a "senior moment"

I agree with Steve's comment on the correlation between internal comments and the bugginess of one's code, which is why I brought up self-documenting code. Coming from the Perl world where programmer self-discipline is required in much higher quantities than in the Java world, I've gone and looked at code that I'd done only a couple of months before and wondered what exactly it was doing. Self-documenting code isn't a panacea, but it does help. Some examples:

* Descriptive member names, e.g., if you're dealing with a List of Book objects, call it bookList
* Descriptive method names,
* etc.

John.

[Frankey James]

thanks for the responses everyone. i read them several days ago, but i'm not allowed to post from work and i've not much time at home lately.