Comment Styles for C-Style Code
Submitted by johnk on Wed, 12/13/2006 - 02:59.
If there's anything that annoys people more than funky indentation, it's bad comments. I don't mean about the code, but in the code.
function name()
{
/* Once upon a time, all my comments
were inside the functions.
*/
}It seemed to makse sense, but there's something that sucks about having to scroll more to start reading code.
/* Moving it up above the function seems to help!
So i did this for a while.
*/
function name()
{
...codehere....
{Lately, all the languages are getting automatic documentation generation. They use comments like this:
/**
* The code comments here get turned into web pages.
* I like how there's a little extra whitespace above and below.
* And the stars are a pain to keep adding, even with editor support.
*/
function name()
{
...codehere...
}But these docs look like really decent docs. In Perl:
#
# This function does nothing at all.
#
sub name
{
...codehere...
}Again, there's all that extra whitespace. It gives the eyes a break.
As you can see, the main trends here are to move the comments out of the function, and to add more visual cues in the comments.