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.

Which language?

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

I mostly use this //comment

In C++ and C and C# and Java and &#106avascript and couple other languages.

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.

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

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.