commenting code (was Re: [thelist] Tip)

Madhu Menon madhum at trisoft.net
Fri Feb 16 00:00:49 CST 2001


> "<!-- Thus endeth the branding. Begin content. The following table
embraces
> the rest of the page. May our readers do likewise. -->"
> 
> *puke*
> 
> Couple things:
> 
> 1) verbosity == file size == page load. Comments are good, but c'mon
people,
> make them to the point, as they affect how quickly the browser can render
> the page. This includes server side comments as well (ASP, CF). The
> client/server parsing engine has to parse comments and code alike. Don't
go
> nuts with verbosity

Spoken like a true programmer, Scott :)
I empathise with you completely.

Seriously though, if your site is going to be maintained by more than one
person, and someone else has to read your code and figure out what's
happening, purple prose won't help at all. It's better to be straightforward
in your commenting.

I disagree with the person who said that the beginning of another comment
signifies the end of the first one. How about something nested like this:

<!-- BEGIN CONTENT TABLE -->

	[Insert HTML here]

	<!-- BEGIN 120*60 button ad -->

		[Insert code for ad here]

	<!-- END 120*60 button ad -->

	[More HTML for content block]

<!-- END CONTENT TABLE -->

In this, the comment for the ad banner doesn't mean the content block has
ended.


When I was at CNET, they followed an interesting style. It's "pseudo HTML"
comments. For example:

<!-- breadcrumb -->

	[Breadcrumb code went here]

<!-- /breadcrumb -->


This would show you the beginning and end of comments without too much
verbosity. If you look at some of the Builder.com pages, you'll see this.


Chris Houston wrote:

> Or even:
> 
> <% ' BEGIN CONTENT %>
> 
> (Or your nearest scripting equivalent)


Um, I don't think you want to do this. Stopping and starting the ASP
interpreter just for the sake of comments will slow your page down. In fact,
one of the ASP performance tips is to keep all your code in ONE ASP block.
And not to do things like:

	<td>Name of subscriber: <%=RsDetails("Subscriber")%></td>

Instead, do: 

	Response.Write "<td>Name of subscriber: " & RsDetails("Subscriber")
& "</td>"


Besides, Why would you want a comment for HTML readability into your
server-side script? The final HTML won't show it anyway, and your goal
hasn't been achieved.

<tip type="ASP" author="Madhu Menon">

This is an often repeated tip, but use the GetRows method of the RecordSet
object. Transfers your recordset to an array. Arrays are faster and it
allows you to close the connection sooner, which is a Good Thing (tm).

</tip>

Regards,

Madhu

<<<   *   >>>
Madhu Menon
Head - User Experience Group
Trisoft Systems Pvt. Ltd.  
Global Software Services

Work: http://www.trisoft.net
Personal rants: http://madman.weblogs.com 

(I hate legal disclaimers like the one below :) 


------------------------DISCLAIMER--------------------------.
The contents of this E-mail (including the contents of the enclosure/(s) or
attachment/(s) if any) are privileged and confidential material of Trisoft
Systems Private Limited and should not be disclosed to, used by or copied in
any manner by anyone other than the intended addressee/(s). If this E-mail
(including the enclosure/(s) or attachment/(s)if any ) has been received in
error, please advise the sender immediately and delete it from your system.
The views expressed in this E-mail message (including the enclosure/(s)or
attachment/(s) if any) are those of the individual sender, except where the
sender expressly, and with authority, states them to be the views of Trisoft
Systems Private Limited.






More information about the thelist mailing list