Tag Archives: comments

Commenting Your Code: A Helpful Habit to Start

“Wait, what? You can put things in your code that are not read by the browser? Why would anybody want to do that?”

When I first started learning how to design web pages, I thought the same thing about using comments, until I started going back through my old layouts to rework and revamp old code for new designs. Boy, had I written myself some head-scratchers. “What in the world is THIS div even doing in the code? It doesn’t have anything in it!” “Huh? What’s this weird padding and margin thing?”

At the time I drafted the older bits of code, I knew exactly what I was doing with the code–I knew exactly what purpose each div, margin, spacer image, and line break was for. But going back to that old code after three or four years? Let’s just say I spent a lot longer than I should have trying to decipher my past self’s reasoning. LOL!

So, to avoid this kind of bafflement every time I go back to an old design, I have resolved to start using comments in my HTML, CSS, PHP, and Javascript codes.

Why Use Comments in Your Code?

As I’ve already said, comments are a great way to remind yourself of why you coded a particular section the way you did. (For instance, reminding yourself that a certain div or code hack is only in place to make IE behave itself. There are plenty of instances of that! LOL!)

But comments aren’t just useful for leaving yourself reminders about code–they’re also good ways to section your code, so that you don’t have to hunt through thousands of lines just to find the one thing you want to fix.

For example, an HTML page sectioned out might look like this:


<!–NAVIGATION–>
<div id=”nav”>

</div>
<!–CONTENT–>
<div id=”content”>

</div>

And a comment-sectioned CSS file might look like this:

/* BODY STYLES */
body {color: #FFFFFF;
background-color: #000000;
…}

/* LINK STYLES */
a:link {color: #FF0000; text-decoration: none;}

Both usages are sanity-preserving (and as web developers, we all know that sanity sometimes is in short supply, LOL). Comments make it possible for you to leave reminders, section headers, and even silly little in-progress notes to yourself to make your job a little more fun.

How to Code a Comment, in Four Different Web Languages

Each Web programming language has its own comment tag style, a way to include things that are only for the web developer to see.

HTML Comments

When you want to start an HTML comment, you place “” after. Like the following:

<!–Woo this is a comment–>

Comments in HTML can be placed anywhere within the <body> tag; the browser will just ignore them.

CSS Comments

When you want to comment in your CSS code, just put a “/*” before you start the comment, and put a “*/” at the end, like this:

/* Yay I have some CSS styles, woot */

You can place CSS comments anywhere in your CSS, whether your CSS is in a separate file or in the <head> section of your page.

PHP Comments

There are two kinds of PHP comment styles–one for comments that only take up a single line in your PHP document, and another for comments that take up multiple lines in the document. (In PHP, lines REALLY matter, so if you’re not sure if your comment will only take up one line of code, best to use the multi-line comment.

Single-Line Comment
To put in a single-line comment, just put “//” or “#” before you begin your comment. Everything to the right of those double slashes or hash symbol will be commented out as long as it’s on the same line as the slashes or hash symbol. Like so:

<?php echo “Whee!”; // a simple little echo statement
# why did I just write Whee? xD
?>

Multi-Line Comment
If your comment is going to go for multiple lines, you’ll instead put in “/*” before you begin your comment, and “*/” after you’ve finished your comment. (Looks identical to CSS!) Here’s an example:

<?php echo “Whee!”;
/* Seriously, why did I just write Whee?  I have no idea.
Possibly because it’s 2 AM and I’ve been staring at this code for hours? LOL */
?>

Javascript Comments

Like PHP, Javascript has two different styles of commenting, depending on if the comment is on a single line or multiple lines.

Single-Line Comment
Doing a single-line comment in Javascript is identical to doing it in PHP–you use “//” before your comment, and everything out to the right of those two slashes will be commented out. Example:

<script type=”text/javascript”>
<!–
document.write(“Hello!”);
//I need to add some more stuff here!
//–>
</script>

Multi-Line Comment
Again, identical to PHP (and CSS), Javascript uses “/* at the beginning and “*/” at the end of its multi-line comments. Makes it pretty simple to remember if you code in multiple languages!

<script type=”text/javascript”>
<!–
document.write(“Hello!”);
/* Here I’ll put in a few more document.write things, as well as some preloaders, but I need to be careful! */
//–>
</script>

References and Further Reading

Here are the sites I used to research this article; they are both great sites to help you learn more about web development of all sorts.

HTML Comments @ W3Schools.com
CSS Comments @ W3Schools.com
PHP Comments @ Tizag.com
Javascript Comments @ Tizag.com

How to Deal with Comments (Both Good and Bad)

More and more, webdesigners and developers are running sites that allow users to comment on articles (such as this blog). This provides a miniature forum experience for the users, and a valuable form of feedback for the content author.

…Well, at least it CAN be valuable, if you know how to extract useful information from those comments. But the process of dealing with comments, even if they are positive and encouraging, can be overwhelming for content authors who are new to the process.

Thus, I have a few tips for handling comments of all sorts, mainly garnered from my own experience as a content author over the last nine years.

Positive/Supportive Commentary: Do’s and Don’t’s

Do:

  • Thank the commenter for their input
  • Visit the commenter’s website, if they have one, and leave a positive/supportive comment on one of their articles, or in a guestbook

Don’t:

  • Ignore or fail to acknowledge the positive comment at all

With positive commentary, it’s pretty easy to handle; we all like getting virtual “pats on the back” for our efforts. Most times, thanking the person and returning the comment favor on their site can be enough. (And who knows, you might find that you and the positive commenter can affiliate or link-exchange, helping to give each other a little traffic.)

Critical/Politely Disagreeing Commentary: Do’s and Don’t’s

Do:

  • Thank the commenter for participating in the discussion
  • Try to answer the points which are being disputed/criticized, in a polite and brief manner
  • Keep the tone of your responding comment positive rather than negative

Don’t:

  • Immediately leap into personal attacks on the critical commenter
  • Delete the critical comment or block its author
  • Bad-mouth the commenter on other websites

Despite our best intentions as content authors, when we write opinion pieces, there are always going to be people whose opinions differ from ours. Differing opinions are okay, as long as all involved parties keep it civil and stick to expanding and fleshing out the topic at hand.

When someone has taken the time to politely disagree with you, and has explained why they have a different opinion, it’s important to answer them as thoroughly as you can, and to thank them for providing a different perspective. Remember, other readers of your blog can be enriched by a balanced group of perspectives, so the critical commenter might actually be doing you a favor!

Abusive/Inflammatory Commentary: Do’s and Don’t’s

Do:

  • Ask the abusive commenter politely to stop what they’re doing
  • Delete their commentary, especially if it is bothering other users
  • Block their IP address from accessing your site, if nothing else works

Don’t:

  • Argue with the abusive commenter back and forth for too long
  • Reduce yourself to their level by making abusive comments back to them
  • Recruit other people to harass them, either on your site or elsewhere on the Internet

Unfortunately, there are some people in this world who thrive on a good debate…except that they define debate as “ticking off everybody on the Internet and having a good laugh at the results.” Rather than being a source for a balanced perspective or polite dissent, the abusive commenter lives to make conflict, spam hateful messages, and incite anger wherever they can.

Deal with them as politely as you can at first; do not mistake a critical commenter for an abusive one, whatever you do. But if the comments the person leaves are taking the focus completely away from the topic, or if they are just hateful spam, then you as the content author (and website owner) need to take action to ensure that everyone who visits your site has a positive overall experience. (Blocking their IP address is a drastic step, but it may be best for everyone involved.)

Summary

Writing for the web means that you’ll be getting commentary of all sorts from others. Learning how to respond to each type of commentary (supportive, critical, and abusive) can help you maintain a better relationship with your users and a better atmosphere for your site.