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.