Forums / Setup & design / Comments in rendered page?

Comments in rendered page?

Next topic

Author	Message
RW Wood	Sunday 28 September 2003 7:23:08 am How do you code html comments in the templates so that they display in the source of the rendered page? the {* comments *} for ezP are lost from the final source. Thanks RWW
Paolo Tramontani	Monday 29 September 2003 2:26:49 am I think you can comment lines in standard HTML mode <!-- --> By this way ezp should pass the html as it is and it should arrive to the browser... I have never tried it but it should work Paolo
RW Wood	Monday 29 September 2003 8:12:59 am That should have been the obvious answer, but the thing that threw me off were the {comment} type comments. What's the reason for doing it that way? The only benefit is that the comments don't show up in the rendered source, when many times it's a comment line that helps track down where there might be a problem. Just like to know the thinking behind the use of that style of comment tags. Thanks. RWW
Paul Forsyth	Monday 29 September 2003 8:35:30 am The {* } comment tags are meant to be used when developing template files, not* for being viewed in the html source. I shouldn't need to what the value of comments are to a developer. If you have written some complex template code and pass it over to another developer it takes a lot longer to decipher what the code does if there are no comments in there. paul
RW Wood	Tuesday 30 September 2003 7:13:40 am No doubt to the need for comments. I just don't see the point of making them invisible in the source of the rendered page. It's not always convenient to turn on template debugging, and for me, the best way to see what's comming from where is a <!-- this is the start of such_and_such.tpl --> in the source. Matter of fact, that's just what the template debugging does is to include comments in the source. More complex comments, such as the ones you refer to are normally not left in the code when a site goes to production, but even if they were, who, other than developers ever would see them? It's not a big deal, but I just don't follow the rationale for using a special tag (which actually has a downside in that in html text editors, the {**} comments show up like {section} or {let} tags, so they're not so easy to spot when scanning through the code. I'm not asking anyone to change it, I just would like to know the thinking behind it. Thanks. RWW
Alex Jones	Tuesday 30 September 2003 7:54:17 am I often use server-side comments like {* } (or in PHP / */ ) when I want to leave notes for other developers or myself. There might be notes about sensitive parts of the code that I don't want exposed to the user or descriptions of logic that is rendered before it ever gets to the browser. In general, I think standard HTML comments should be used sparingly as they do the user little to no good. They add additional weight to the page which can add up over time. If I need to see what template is loaded then a temporary HTML comment works, but if I want to keep track of what the code is doing in a template, then server-side comments are ideal. My thoughts, Alex Alex [ bald_technologist on the IRC channel (irc.freenode.net): #eZpublish ] <i>When in doubt, clear the cache.</i>
RW Wood	Tuesday 30 September 2003 8:02:58 am I would agree with Alex, however, I don't find many of those kinds of descriptions in the design templates. Maybe I haven't searched far enough. But if you look at pagelayout.tpl in the standard design, the "invisible" comments are being used in the way that I suggested they would be more benefial to be seen in the final source. Not having seen them used in the way that you pointed out, I could see no need for making them that way. RWW
Paul Forsyth	Tuesday 30 September 2003 8:12:38 am This boils down to best practice for coding web pages. Each different view can be right and wrong depending on your circumstances. From my own point of view working with many projects i heavily re-use my own templates. Coming back to something a few days/weeks/months old can be made very easy by commenting code properly. Since the end user can never see {* } comments I can write comments as i like. I also work with my servers in a local environment, testing the code in several ways, on-screen feedback, using 'tail -f' var/log/.log, etc. Only if there is a problem would i need to turn on debugging on a live site. It may one day be possible to use a proper documentor ala doxygen,javadoc to parse the ez template code in some useful way... Not sure how useful but i like programs that create documentation for me in a structured manner. These points work well in a multi-project environment. Almost essential. But for a small number it probably isn't necessary. I consider myself a software engineer given my background and i've come to rely on certain best practices when it comes to code. Paul