Comments Are Code

SomeCommentsAreReallyCode

"Comments" in your program that are processed in special ways by your development tools aren't just comments -- they're CODE.


        Question::	Why does this matter?

        Answer::	When using a methodology that limits your use of comments (like ExtremeProgramming) comments subject to special automated processing don't really count as comments.

Examples of comments intended for special processing:

unix shebang (#!/bin/bash, ...)
JavaDoc -- /** @name parms */
PythonDocstrings -- available at runtime (eg. for interactive documentation reading)
- Not really--they aren't comments at all. They're program statements (strings, to be exact) that are _used_ as comments. Quite different.
SQL optimizer "hints"
- Oracle -- "select /*+ FULL(table_name) */ column, ...", "select /*+ INDEX(table index) */ column, ..."
- Sybase/SQL Server
lint -- /*NOTREACHED*/
round-trip engineering markers
- Togethersoft TogetherJ
- Rational Rose
- VisualStudio extensions
Source code control macros
HTML client-side code (typically put into HTML/SGML/XML "comments") --
HTML server-side code (shtml 'comments')
local tools
- FixmeComments

Perl POD anyone?

The code you write as "code" needs to...

instruct the machine
inform the poor sap who comes later. The code, nearly always, will be what and how, seldom why. And why is the domain of comments. So the code you write as "comments" needs to
instruct/inform the poor sap who comes later, so he doesn't retrace your steps through the swamp. You're not programming the machine at this point, but the poor sap.

I dare to state that every time you add comments to your code you are writing instructions to your code management tools (version control, project management, source navigation, automated testing, user documentation, etc.), or else your development environment is obviously flawed.

I'm not 100% sure that I'm right, so I want to see some counterexamples. And please don't fear to be wrong yourself, as it will help you, me, and others -- NikitaBelenki

So, anyone?

When I write Perl, I either use vi or a text editor in MS-DOS. At what point are the comments anything other than syntax?

When you use grep, I think :)

When I write C++, I use VC++6. Comments are either VisualStudio extensions (in which case they are coloured grey), or they are comments proper, in which case they are merely comments.

Can you show an example of the code that contains "merely comments"?

When I write Java, JavaDoc really is code. But it's illegal (as in by the courts) to extend the language through comments, unless you are Sun. So, comments are comments, unless they are JavaDoc. (*)

So it can be that either JavaDoc comments are sufficient, or Java sucks. Not a counterexample. Although there is an interesting question. Some version control systems use pseudocomments to put their stuff into the code. Is it illegal to use them with Java?

: Dunno. Ask ScottMcNealy.

On the other hand, in the sense that TheSourceCodeIsTheDesign, and you want SelfDocumentingCode via LiterateProgramming, comments as code is an important realization.

See FileHeaders for an example of where comments aren't code in the sense they do anything, but they are an important part of the code.

I would say that if you have ever run anything like perl -e 'while(<*>){ open F,$_; print scalar() for(1..2); }' against your codebase then this is a good example of CommentsAreCode.

(*) The motivation is to avoid language forking through third-party extensions. Another example of Sun (arrogantly?) dictating how developers will solve problems. Where Perl's motto is "there is more than one way to do it," Java's is "there is only one way to do it." This is really against the CommentsAreCode hack. And a hack is really what it is. See the