Sign in to follow this  

real-world code comments

This topic is 4865 days old which is more than the 365 day threshold we allow for new replies. Please post a new topic.

If you intended to correct an error in the post then please contact us.

Recommended Posts

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?

Share this post


Link to post
Share on other sites
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

Share this post


Link to post
Share on other sites
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:

/* --------------------
* 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...

Share this post


Link to post
Share on other sites
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.

Share this post


Link to post
Share on other sites
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:


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

Share this post


Link to post
Share on other sites
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

Share this post


Link to post
Share on other sites
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.]

Share this post


Link to post
Share on other sites
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.

Share this post


Link to post
Share on other sites
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.

Share this post


Link to post
Share on other sites
Quote:
Original post by Glass_Knife
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


I worked at a place like that once. My honest advice on that is to start searching monster.com.

Share this post


Link to post
Share on other sites
I usually write comments if I have a method that has a whole list of code thats split into paragraphs.

eg

//gets whatever
code-code-code-code-code-code-code-code-code-code-code-
code-code-code-code-code-code-code-code-code-code-code-
code-code-code-code-code-code-code-code-code-code-code-
code-code-code-code-code-code-code-code-code-code-code-
code-code-code-code-code-code-code-code-code-code-code-

//Updates stuff
code-code-code-code-code-code-code-code-code-code-code-
code-code-code-code-code-code-code-code-code-code-code-
code-code-code-code-code-code-code-code-code-code-code-
code-code-code-code-code-code-code-code-code-code-code-
code-code-code-code-code-code-code-code-code-code-code-



Like only if the code in the paragraph looks a bit messy and you can't help it, so when you might need to fix something and have to find that piece of code, you know which paragraph it'll be in.


Share this post


Link to post
Share on other sites

This topic is 4865 days old which is more than the 365 day threshold we allow for new replies. Please post a new topic.

If you intended to correct an error in the post then please contact us.

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now

Sign in to follow this