Sign in to follow this  
chefgon_ign

commenting standards?

Recommended Posts

Is there a set of standards for code commenting? I usually either make little notes to myself or just leave out the comments all together. I'm making a few short coding samples that I could show to employers if I wanted to, and I can't do that until I have some professional looking comments.

Share this post


Link to post
Share on other sites
Which language?

Also, if they are looking at meaningful comments, not by LOC, then putting in comments as an afterthought is usually futile.

Share this post


Link to post
Share on other sites
Quote:
Original post by PhoenixAdmin
I mostly use this //comment

I don't think that's what he was talking about.

My approach to comments is pretty straightforward: I comment something if and only if it would help someone unfamiliar with the code figure out what's happening. That leads naturally into the "why not how" guideline frequently cited, but it also means describing a lot of structure. "EntityOperator" is not as self-explanatory a class as one might think when writing it; judicious use of comments really helps in describing where it fits into the grand scheme of things.

Share this post


Link to post
Share on other sites
Quote:
Original post by Julian90
Some Previous Threads:
...
do you comment?

Ooh boy I remember that thread :P I created it after writing my article The Art of Code Documentation. Uhm, yea I was just a tad bit overzealous in my commenting practices back then - it's not a good thing to write while bitter. I should really re-write this article *adds ToDo* but in the meantime it's still something.

Share this post


Link to post
Share on other sites
If you have some documentation tool (javadoc, msvc#'s comments to xml stuff) do that. If you have to hunt for a bug, add a comment where you fixed the bug so someone doesn't reproduce it. If you deviate from a known pattern or practice for a particular reason, add a comment with the 'why' of it. If you don't quite finish something or are leaving something out for some reason // TODO: it.

Share this post


Link to post
Share on other sites
I find that just about the only things I comment all the time are base classes, interfaces, virtual / abstract functions, singletons or static variables, application initialization / teardown, and places that eat exceptions (catches that don't log or rethrow). I comment all of the above becase - the base type stuff needs to document the CONTRACT that it expects all derived classes will adhere too ... it can't very well assume that each future implementor knows magically what must be remembered about the pre / post-conditions, etc. The singletons and static variables I comment because they are just the modern version of shared global variables (of course safer than globals, but still able to be widely shared via fairly loose coupling) and therefore I document what is assumed (such as when they are or or not valid, or how they are supposed to be used). The exception eating code simply because since there is no code to explain what the code is doing, the comments must explain why there is no code :) ... and I find that I have to comment the initialization and teardown a little so that the less-than-obvious ordering dependencies that exist in most apps can be brought into the light for all to see.

But by and large I comment by writing good code. I spend the 5 minutes needed to refactor my base class or interface names for that reason alone. And if I figure out better naming 3 days later, I refactor it again. Until such time as the team is getting too used to the heirarchy and arangement to the point that name changes would confuse them I constantly search for exactly the right (accurate) naming for everthing ...

Share this post


Link to post
Share on other sites
I [try] to comment only the things that I feel need commenting.
ie, has some value that may describe the code, and its purpose.

As for an actual standard, I use /* */ for class header information,
and // for single line comments.

I personally prefer using #if 0 in place of /* */ though if commenting out
code.

I do basically the same in assembly language--just a little more.

Share this post


Link to post
Share on other sites

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