Commenting your .htaccess code is an important part of staying organized. Here are some quick tips and best practices for writing comments in your .htaccess file (or the Apache server config file).

Pound Sign

Each line of comments must begin with a pound sign, or hash tag, or whatever you want to call it, #. Adding a pound sign before your comments tells Apache to ignore the line. For example:

# this is a comment

Prepending a line of .htaccess directives with a pound sign is a quick way to disable the entire line, which is super useful when troubleshooting and customizing code.

Entire Line

In newer versions of Apache, writing a comment requires the entire line. That is, when you add a pound sign to make a comment, it must be the first non-blank character on the line. If you add any non-blank characters before the pound sign, say hello to one of those nasty 500-level server errors.

So for example, any of these comments is legit:

# this is a comment
     ## this is another comment
                  ### multiple pound signs are fine

But these examples are not legit, and will produce an error:

ExpiresActive on # this will trigger an error
RedirectMatch 403 /spamhole/ # this will trigger an error
# this will
           trigger an error

So basically if you want to include a comment, best practice is to put a pound sign at the beginning of the line, so that Apache knows to ignore it.

Same Line

In earlier/older versions of Apache, I remember it was okay to include a comment at the end of a line (wrapped in double quotation marks), like so:

<Limit GET POST PUT>
	Order Allow,Deny
	Allow from all
	Deny from 111.222.333 "# sesame street"
	Deny from 444.555.666 "# mister rogers"
	Deny from 777.888.999 "# power rangers"
</Limit>

That technique was extremely useful and awesome, but unfortunately it no longer is allowed in newer versions of Apache. So as much as it may help to organize your code, don’t do it. Keep your comments each on their own line, as discussed previously. I mention this here because there are still examples floating around on teh Interwebz that employ such syntax.

Anywhere in the File

You can add a line of comments anywhere in the .htaccess file (or server config file). Top of the file, middle, bottom, or anywhere in between, adding a line of comments wherever you want is completely acceptable. This is the case with most coding languages, but I thought I would mention it here for anyone who might be wondering.

Keep it Clean

Keep your comments clean and simple. In my experience, it is a good idea to write your comments as clear and concise as possible using only alphanumeric characters. It’s fine to include the occassional period, comma, dash, or whatever, but once you start straying too far into “weird” character territory, you never know if Apache is going to trip up and incorrectly parse something unexpected. I try to always limit my own .htaccess comments to alphanumeric characters only. Go ahead and call me paranoid for doing this, but I am convinced that it helps to prevent errors.

Don’t Go Crazy

One last tip about commenting your Apache directives: keep the number of comments succinct and to a minimum. This helps to minimize the amount of time required by Apache to parse the file. That is, if you go crazy and add mini-novels worth of comments in your .htaccess file, it’s gonna require a bit more time and resources to parse the document. So either keep the comments to a minimum, or else remove them from the file before moving to a live production environment.

If you’ve read this far, congrats! You are a fellow .htaccess geek :)