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(<F>) 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 <STYLE> tag in DHTML. So I can't really say whether this philosophy is good or bad. I'd rather have good languages, but I recognize the pragmatic need to get something done now with the existing languages. -- SunirShah

My point was that comments are either a part of well-organized data for your development tools, or not the best location to put the information in the first place. So if the CommentsAreCode is a hack that you don't want to use, your development tools shall do such a good job that you would never need to put any comment directly into your source code.

But you have reminded me of the example where I'm probably wrong: short scripts that aren't (yet) an integrated part of the development process. Does anybody have another one?

I see your point. Comments have syntax you can match against. Actually, most C compilers have a mode that will dump the comments to stdout as it goes through the code. Also, a complete XML parser will return comment objects if you want it to. -- ss

Whether or not your assertion proves to be true, I find it extremely thought provoking. Let me attempt to state it another way, and you can tell me if I'm correct in my understanding.

I think many of us draw this distinction between code and comments:

Code conveys information to a computer and to other developers.
Comments convey information only to other developers.

There seem to be two parts to your assertion:

Any comment that is parsed by a development tool should really be considered code, based upon the above definition.
Any comment that is not parsed by a development tool either adds no value or provides evidence of a flaw in the suite of development tools.

Is this what you're suggesting?

-- CurtisDuhn

Yes. Even if the information is intended for humans, it usually should be accessible not only by browsing through its location in the source code. And also even if it is intended for humans, it sometimes can be organized so that its accuracy can be checked automatically.

I like the code/comment distinction above. As to the "two parts to your assertion...", I think part #1 is right on, but that the point of the original authors is that development tools that require additional information to be imbedded in comments are flawed. So point #2 is off: It's not that comments for developers only indicate a problem with the tool, it's that the tools use of language comments for other purposes is a hack. -- JeffGrigg

Well, Jeff... seems like you are assuming that there is something that is not code (but "just comments") and that should sometimes be put into the program's source code. Could you please provide some examples? -- NikitaBelenki

I should read more carefully: I now see that your original comment, NikitaBelenki, was that comments intended only to be read by developers are either useless or indicate a flaw in the development environment. I was distracted by SunirShah's comment that "special processing" comments (#1 above) are a hack -- and also indicate a flaw in the development environment and/or language. I agree with both statements.

The point where I would differ is that I think there are really three points to #2 -- if you have comments that aren't parsed by a tool and aren't needed to make up for flaws in the tool and they're not useless, then they're probably there because the code is poorly written. (I work with a lot of very poorly written code. I write lots of comments. I also refactor, but it's a long slow process.)

-- JeffGrigg

But even if the code itself is poorly written, aren't there better places to put the comments? --nb

Proposal:use comments in wiki such as // to provide machine readable content. Since text by default is now all comments, AntiComment s could allow definition of basic attributes and methods which would go through the regular review process till everyone agrees what they are. For example see ObjectCircle and compare what was there about circles before. Similarly if a machine was trying to query wiki right now about what an address is it would find a lot about ips but not the fact that there might be a category involving street, unit, state, country. A proxy program somewhere could then translate these to xml/soap to provide an interface.

See OnceAndOnlyOnce, FixmeComment, IdentifiersAreComments, UseCodeToBookmark, UnitTestAsTickler, CommentTheWhy

CategoryCodingIssues