Programming Language Grammars – How Are Comments Expressed?

Constantly

I really can't believe I'm the only one swimming in outdated and misleading comments. In the off chance this helps with understanding:

It probably depends most importantly on the age of the code. The next factor would be turnover on the staff.

I do equal parts R&D and maintenance work. The R&D is new code, generally stuff that's a little off the beaten path. Many of my colleagues believe in putting in a lot of commented explanation when trying something that there isn't a library already out there for. Since the comment to code ratio is higher than normal there's just more opportunities for things to go out of sync.

The maintenance code...I'm an active maintainer on a system that is over 10 years old and another that is over 5. The 10 year old code and comments are atrocious, as you'd expect. Over 10 years you get a lot of hands in the codebase and no one has any idea how the whole thing works anymore. The 5 year old code and comments are pretty good because the turnover on the team has been pretty low.

I work almost all services, even our products are highly customized to a particular customer.

Specific examples:

• Comments describing the performance improvement for a particular methodology, like avoiding an in-memory copy. A big deal when a top end machine in a Pentium 2 with MBs of RAM, but hardly a problem now.

• TODOs

• Blocks of copy-pasted code including comments. Comment may have made sense in its original location, but hardly makes sense here

• Comment blocks on top of commented out code (Who knows how many years that's been in there).

In all these you see a trend of just not maintaining the comments and code at the same level as the software. IDEs and basic developer habits don't help with this, my eye has been trained to speed past them. I think comment outdated-ness is relatively cheap to avoid in green-field and active projects. If you can keep the code/comment ratio high, it's not a big deal to keep them up to date. It's a little harder to justify hunting these things down when you're budgeted x hours for a bug fix on a production system.

Usually comments are scanned (and discarded) as part of the tokenization process, but before parsing. A comment works like a token separator even in the absence of whitespace around it.

As you point out, the C specification explicitly states that comments are replaced by a single space. It is just specification-lingo though, since a real-world parser will not actually replace anything, but will just scan and discard a comment the same way it scans and discards whitespace characters. But it explains in a simple way that a comment separates tokens the same way a space would.

The content of comments are ignored, so linebreaks inside multiline comments have no effect. Languages which are sensitive to line breaks (Python and Visual Basic) usually do not have multiline comments, but JavaScript is one exception. For example:

return /*
       */ 17

Is equivalent to

return 17

not

return
17

Single-line comments preserve the line break, i.e.

return // single line comment
    17

is equivalent to

return
17

not

return 17

Since comments are scanned but not parsed, they tend not to nest. So

 /*  /* nested comment */ */

is a syntax error, since the comment is opened by the first /* and closed by the first */