real-world code comments
I am happy to say I got my first job as a programmer. It is not with a game company, but thats ok. My question is this. Of all the code at work, most of it has little to no comments. After speaking with some friends that are also programmers, they informed my that this is nothing new. Is this the way things are, and if not, how should I go about fixing this?
Code comments are often unnecessary. Particularly with short self-explanatory functions.
Good form suggests that a function body should fit on one screen (screen size being usually <50 lines).
If the function is fully documented using some form of inline documentation (like Javadoc), then a 50-line function should be understandable, unless it's written in a really obscure style.
Place comments to explain anything counter-intuitive. Don't use comments to explain what code is doing - that should be obvious. Use comments to explain why it's doing it.
One method I sometimes use is to write the function in pseudo-code and then leave the pseudo-code in, while fleshing out the function.
But make sure that if you refactor the function later, you also refactor the comments.
Mark
Good form suggests that a function body should fit on one screen (screen size being usually <50 lines).
If the function is fully documented using some form of inline documentation (like Javadoc), then a 50-line function should be understandable, unless it's written in a really obscure style.
Place comments to explain anything counter-intuitive. Don't use comments to explain what code is doing - that should be obvious. Use comments to explain why it's doing it.
One method I sometimes use is to write the function in pseudo-code and then leave the pseudo-code in, while fleshing out the function.
But make sure that if you refactor the function later, you also refactor the comments.
Mark
In terms of time, it is much easier to just get the job done and not worry about comments - the problem lies when you come back to a piece of code a couple of months later and you have to then waste time to figure out what it does. A couple of tips:
1) make the code readable (good variable names, clear indentions, etc.)
2) make the code flexible - easy to expand without breaking anything else
3) after a while, take some time to do some limited comments. Put a couple of lines in for the beginning loops to let you know what's going on inside the loop, short comments on odd variables and math-spots.
I made a couple of macros to quickly create fill-in function comments such as:
and place these at the beginning of (non-trivial) functions. They come in handy when you have a lot of code to sift through to find out what things do after you haven't looked at the code in a while...
1) make the code readable (good variable names, clear indentions, etc.)
2) make the code flexible - easy to expand without breaking anything else
3) after a while, take some time to do some limited comments. Put a couple of lines in for the beginning loops to let you know what's going on inside the loop, short comments on odd variables and math-spots.
I made a couple of macros to quickly create fill-in function comments such as:
/* -------------------- * Function: <name> * Input: <var 1 description>, <var 2 description>, etc. * Output: <output description> * Description: <what it does> *--------------------*/and place these at the beginning of (non-trivial) functions. They come in handy when you have a lot of code to sift through to find out what things do after you haven't looked at the code in a while...
I'd strongly advise you to comment. You think clear code is fine, but our system is hundreds of projects using COM interfaces etc. Some of it hasn't been changed for >5 years. When I started the whole project was just so huge you couldn't figure it out at all, except that there were fairly decent comments describing how different components interacted etc.
I believe it's common for companies to have a policy on commenting ie you have to.
I believe it's common for companies to have a policy on commenting ie you have to.
It all depends on the company.
Don't put comments in code that isn't yours. Hell, they might fire you for that.
Don't over comment, don't undercomment...use common sense.
Nobody needs to know that you //assign 4 to NumThings
Personally, I say comment like this:
1.) Put a brief comment at the top of every function to quickly explain what it does, such as:
2.) Comment any code that isn't 'obvious' to a relatively knowledgeable programmer. Yes, brilliant programmers may never need to read your comments, but don't assume everyone on your team is brilliant.
Don't put comments in code that isn't yours. Hell, they might fire you for that.
Don't over comment, don't undercomment...use common sense.
Nobody needs to know that you //assign 4 to NumThings
Personally, I say comment like this:
1.) Put a brief comment at the top of every function to quickly explain what it does, such as:
//----------------------------// DoSomethingReallyCool()// Does something extremely cool// In fact, it's so cool your face// might explode.//-----------------------------void DoSomethingCool(){}2.) Comment any code that isn't 'obvious' to a relatively knowledgeable programmer. Yes, brilliant programmers may never need to read your comments, but don't assume everyone on your team is brilliant.
Thanks for everyone's input on this. I know that from where I sit, I wish the code was commented. I don't expect everything have a comment, but there are none. Not a single comment. There are also about 30+ projects, each using parts of others. I can understand needing to get the job done and not worrying about comments fi the code is readable, but some stuff is not understandable without sifting.
Thanks
Thanks
Generally there's at least design documents and the such which lay out what does what, and how things interact. Usually on some internal website, or in handy dead-tree form. Ask around.
Though a dev team being pushed so hard that they don't document or plan isn't exactly unheard of either...
[edit: PS, congrats.]
Though a dev team being pushed so hard that they don't document or plan isn't exactly unheard of either...
[edit: PS, congrats.]
Ask co-workers for the amount of comments they'd like to see and go for it when you are writing new code. Don't ever let the status quo dictate how you write code -- that is the fast track to not standing out.
My experience has been much different. I'm in the engineering field, and our code is all peer-reviewed. If anything's ever the slightest bit unclear, the feedback is always "better comments, more comments, clearer comments". We're quite fanatic about it. Of course, I believe we also produce exceptional code. I think we're a rare case given the other code we've seen.
This topic is closed to new replies.
Advertisement
Popular Topics
Advertisement