Game_Ender

When I code I write a classes header file first, then comment the class, its member functions and variables in doxygen style. Then I actually write the class. This is followed by a unit test suite that tests to make sure every method of the class does what the documentation says it does. This is all quite helpful in forcing you to design your classes well. This all goes along with proper variable and function naming.

I would like to say the people who claim there code is "self-documenting" have not come back to code they wrote a long time ago. Self-documenting is true for body of simple functions, but you can't expect a function name to convey as much information as this. Ogre is quite a good project to see how a pretty well written, documented and layed out project should look like.

msk420

New guy sounds smart.... Welcome to the PFO forums...

__________________
Code Forums

Game_Ender

I have been scared straight by looking at several awful C++/C applications. All you have to do is spend several plowing threw it before you want to just sit down and rewrite the whole thing. After all, what decent engineer doesn't stare at a system and think they can do it better . That said it really does take quite some time to do the whole the Document-Code-Test cycle, but at least it gives you a safety net. Most of the stuff I code has to be used by other people, so the more copious my documentation and testing the more effective it will be.

msk420

I agree. The apps I work with/on are used by other people and if they need to look at the source and its not commented they have no idea what I am talking about.

__________________
Code Forums

Eric the Red

I comment everything!!!! line by line, even if it's wrong to do so.

This is mainly due to the fact that I have a horrible memory and so the comments help me remember what I'm doing.

__________________
Death smiles at us all. All a man can do is smile back.

msk420

Good practice I guess...

__________________
Code Forums

Jimbo

I'd say overcommenting is actually not good. While you can definitely see what your code does later, well, if you need the comments on every line later, you might not want to be programming much. But even when you're first writing the code, if you comment each line, you're spending a rough estimate of 30-50% of your coding time writing comments. Not particularly efficient. That's not to say that spending a certain amount of time on commenting is bad, but there's such a thing as too much.

msk420

True I see your point.

__________________
Code Forums

Harakim

That's my code you're talking about. That is why I started commenting.

Eric the Red

That's true. However, I comment a lot because my teacher gives the class a communication mark based on the amount of comments we have.

__________________
Death smiles at us all. All a man can do is smile back.