8
 <body>  
  <!-- wrapper -->  
  <div id="wrapper"> 
   <!-- title -->
   <div id="title"><img src="title.png" alt="" /></div>

   <!-- form wrapper -->
   <div id="form_wrapper">

    <!-- form -->
    <form action="thankyou.php" method="POST">
     <!-- ... ... -->
    </form>
    <!-- /form -->
   </div>
   <!-- /form wrapper -->
  </div>
  <!-- /wrapper -->
 </body>

I can almost understand the <!-- /wrapper --> at the end, because it's so far from the start of the tag/pair... but seriously, what's the point of the opening comment lines? I wouldn't ask the question if I didn't see this all the time.

I feel as if I'm missing something. Maybe there's some unwritten best-practice involved, though I fail to comprehend what it could possibly be. More than likely it's just obsessive-compulsive behavior.

How do you guys normally comment your markup, if at all?

8
  • possible duplicate to: programmers.stackexchange.com/questions/4858/… – Chris Oct 27 '10 at 22:10
  • 1
    I think I'm going to start doing that. – Peter Turner Oct 28 '10 at 2:11
  • 1
    While this kind of thing can be handy when it works, I've seen those comments get divorced from their associated tags after a while, and then they are actually doing more harm than good. – Rohan Singh Jan 20 '12 at 18:40
  • 1
    this is a tautology at best and dangerous anti-pattern at worst, as soon as someone edits this mess the comments will get out of sync with reality and be more of a mess than without them. Proper formatting and good IDE makes this kind of crap useless! – user7519 Jan 20 '12 at 20:05
  • 1
    I guess the real reason why some devs might prefer this style is that it looks symmetric - lots of mediocre devs prefer to write symmetric code without wasting a thought if this makes really sense or is fully braindead. This is sometimes called "programming by coincidence". – Doc Brown Sep 21 '15 at 5:42
9

Some times CSS class names are generic and aren't specifically named. For example, what if you had

<!--Code before-->



<!--Column one-->
<div class="center-bold">




    <!--Tons of lines-->




</div>
<!--End column-->

Wouldn't it be nice to know what your starting? I surely wouldn't want to scroll all the way to the end to find out that the whole div was a column.

3
  • Acceptable only because the "opening" comment identifies a markup element that is not already identified with an ID or descriptive class. – Stephen Oct 28 '10 at 11:35
  • 3
    I guess what bothered me most were redundancies like </form><!-- /form --> and <!-- wrapper --><div id="wrapper"> – Stephen Oct 28 '10 at 11:36
  • This is what I was getting at, your example is just more explicitly laid out. Good answer! – Chris Oct 28 '10 at 19:23
6

HTML is like compiled code to me. It's optimized, has no spaces, no comments, and is as small as possible while getting the job done. I do, however, have some comments in my templates which generate the HTML files. You'll never see them though, unless you join the dev team!

Same thing goes for JavaScript. Any JS you see on my site is compressed, minified, and has the comments removed. Comments are for developing, not for wasting bandwidth!

4

Usually my markup is generated dynamically so comments are not included... but when I do write markup I will have:

<!-- start BLOCK--> 
  html markup 
<!-- close BLOCK--> 

It makes it easier for me to see where major blocks/divs are within my code.

1
  • I totally agree. – Evik James May 4 '11 at 18:23
2

I believe this comes from documents that do not have proper indention. So, if you can't tell where you are from the column you are in - then next best thing is to look at the comments. It seems to have evolved from this dilemma.

Personally, I would get on the people who are not indenting code.

1

I can only think of one valid use case for this: partial HTML templates.

If it's a full HTML page, then you should indent properly to make it easy to identify when elements start and end. Decent editors also highlight the opposite ends of tags. In these cases, extraneous comments are annoying.

If it's a partial template (header and footer, for example), then if you are opening up some page containers, it may be useful to show in the footer where it ends.

header

<div id="header">
    ...
</div>
<div id="contentContainer">
    <div id="content">

footer

    </div> <!-- /#content -->
</div> <!-- /#contentContainer -->
<div id="footer">
    ...
</div>

In (perhaps more complex) cases like this, having the comments are quite helpful to see what tag it is supposed to be closing. This is the only case I've come across where I don't mind these comments, though, they still feel dirty.

1
  • Yes, with things like views and templates this often does pose a problem as each segment is offen indented only to that file's specific code. – Xeoncross Jan 20 '12 at 18:41
1

This is useful if the page is rendered by multiple different files/templates, etc.

Something like this:

<?php

echo "<!-- sidebar -->\n";
include("sidebar.php");  
echo "<!-- /sidebar -->";
# Or better yet, put the HTML comments *inside* sidebar.php
?>

That way if you notice some strangeness in your rendered HTML, you can quickly track down the code that made it.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.