Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.
 <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?

share|improve this question
    
possible duplicate to: programmers.stackexchange.com/questions/4858/… –  Chris Oct 27 '10 at 22:10
    
Maybe the last question is similar, but not the first. –  Stephen Oct 27 '10 at 22:11
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! –  Jarrod Roberson Jan 20 '12 at 20:05

6 Answers 6

up vote 8 down vote accepted

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.

share|improve this answer
    
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

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!

share|improve this answer

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.

share|improve this answer
    
I totally agree. –  Evik James May 4 '11 at 18:23

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.

share|improve this answer

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.

share|improve this answer
    
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

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.

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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