Comment your code—it’s a mantra they drill into you in Programming 101. I know, most of us took that class at age 5 or 6, but it’s still important 30 years later.

Of course, in those bygone days, we were probably programming in C (or maybe Java for you young’uns, or FORTRAN for the graybeards). Comments were there for your benefit as a programmer, and the compiler helpfully threw them away when building binaries for end-user consumption. You could put anything you wanted into your comments and not worry about them becoming public knowledge. Anything, including:

C XOR WITH 42405 TO ENCRYPT MY SECRET VALUE

or

/* This paranoid and performance-killing logic is here because
   the customer is a clueless f***ing anal-rententive nutcase. */

or

// I have a crush on the chick in the next cubicle.

and only the other developers could see them. Of course, if the girl in the next cubicle was also a developer, it wouldn’t be terribly smart to put such a comment in your code. And that’s what I want to talk about, because this sort of thing seems to be happening more often than it should…

The danger of HTML comments

In this era of high level languages and web development, you have to be careful because not all code is compiled, and sometimes comments end up visible to end users. Comments in HTML are a particular culprit. Anything you put into an html document, including:

<!-- This is our top-secret widget but I'm commenting
     it out until our launch date.
  <div> ...
-->

is visible to any user who knows how to “view source” in a web browser. I’ve viewed-source on a lot of web sites, and seen a lot of html comments that probably should not have been exposed to the public. At worst, these can be embarrassments, or even security holes.

Similar issues surround documents served directly out of your public directory, such as javascripts and stylesheets. Any such files can be found and viewed directly by anyone with a passing knowledge of html. Do you think no one will look at your CSS files? I’ve done so many times, studying how other sites style their pages, and I’m sure I’m not the only one. And you don’t want to know how many times I’ve seen something like this at the top of someone’s publicly-visible CSS file:

/*
   $HeadURL: http://192.168.3.8/website/trunk/public/css/main.css $
   $Revision: 2343 $
   $Author: johndoe $
*/

You don’t really want me to see your subversion header and gain information about your development infrastructure, do you? Then don’t include it in those files, or write some logic in your production deployment process that strips it out. Better yet, use an optimization/obfuscation tool, especially for javascript. You’ll hide sensitive comments, and make your users happier by reducing load time and bandwidth.

A simple solution for Rails views

When writing a Rails view using erb/rhtml, don’t use html comments unless there’s a genuine functional reason it needs to be in the final html document itself. Instead, erb supports a syntax for ruby comments that will not be rendered into the final document:

<%# This is a comment that will not be rendered %>

But sometimes, don’t we want those comments there for development and testing purposes? Perhaps, as I’m debugging a view, I want to visually delineate sections of an html document, or display a value in a comment, but not show (or spend time computing) that value in production. We’ve written a simple method in our ApplicationHelper to make this easy:

module ApplicationHelper

  def c(str="")
    if RAILS_ENV == "production"
      ""
    else
      str = yield if block_given?
      "<!-- #{str} -->"
    end
  end

end

Now, in our rails views, we can do the following:

<%=c "Starting Login Widget" %>

You can recognize this line as a comment in your .html.erb view file. Furthermore, the comment is rendered into the html document in development, test, and staging environments, but not in production. If a comment requires some computation, we pass in a block instead:

<%=c {"The value is #{perform_long_computation()} here."} %>

The computation is run and the comment is rendered in development, test, and staging, but the computation will not even execute in production.

Conclusions

No one doubts that ample and strategic commenting is essential in any software development project. But web developers need to be conscious that some of their code can be viewed by an end-user. I don’t know, this all seems obvious to me, but I’m still amazed how many times I’ve seen potentially sensitive comments plainly visible in html. You need to assume that your users are viewing-source, and manage your comments, especially sensitive comments, accordingly. A simple tool like the one above can be a great help.