Commenting Your Code


The last introductory topic I want to mention is commenting your code. Many books leave this to the very end, but I believe it is so important that I am introducing the concept right herebefore you start real coding.

The code you have worked with thus far has been short, simple, and pretty self-explanatory. But as you start building bigger and more complex applications, your code will become more involved and more complex, and comments become vital. Here is why you should comment your code:

  • If you make code as self-descriptive as possible, when you revisit it at a later date you'll remember what you did, and why.

  • This is even truer if others have to work on your code. The more detailed and accurate comments are, the easier (and safer) it will be to make changes or corrections when necessary.

  • Commented code is much easier to debug than uncommented code.

  • Commented code tends to be better organized.

And that's just the start of it.

Listing 8.13 is a revised version of hello6.cfm; all that has changed is the inclusion of comments. And as you can see from Figure 8.17, this has no impact on generated output whatsoever.

Listing 8.13. hello7.cfm
 <!--- Name: hello7.cfm Author: Ben Forta (ben@forta.com) Description: Demonstrate use of comments Created: 12/1/2004 ---> <html> <head>  <title>Hello 7</title> </head> <body> <!--- Save name ---> <cfset firstName="ben"> <!--- Save converted versions of name ---> <cfset upperFirstname=UCase(firstName)> <cfset lowerFirstname=LCase(firstName)> <cfset reverseFirstname=Reverse(firstName)> <!--- Save name length ---> <cfset lenFirstName=Len(firstName)> <!--- Save repeated name ---> <cfset repeatFirstName=RepeatString(firstName, 3)> <!--- Display output ---> <cfoutput> Hello #FirstName#, and welcome to ColdFusion!<p> Your name in uppercase: #upperFirstName#<br> Your name in lowercase: #lowerFirstName#<br> Your name in reverse: #reverseFirstName#<br> Characters in your name: #lenFirstName#<br> Your name 3 times: #repeatFirstName#<br> </cfoutput> </body> </html> 

Figure 8.17. ColdFusion comments in your code are never sent to the client browser.


Comments are typed between <!--- and ---> tags. Comments should never be nested and should never be mismatched (such as having a starting tag without an end tag, or vice versa).

NOTE

ColdFusion uses <!--- and ---> to delimit comments. HTML uses <!-- and --> (two hyphens instead of three). Within ColdFusion code, always use ColdFusion comments and not HTML comments. The latter will be sent to the client (they won't be displayed, but they will still be sent), whereas the former won't.


CAUTION

Be sure not to mix comment styles, using two hyphens on one end of the comment and three on the other. Doing so could cause your code to not be executed as expected.


TIP

Commenting code is a useful debugging technique. When you are testing code and need to eliminate specific lines, you can comment them out temporarily by wrapping them within <!--- and ---> tags.




Macromedia Coldfusion MX 7 Web Application Construction Kit
Macromedia Coldfusion MX 7 Web Application Construction Kit
ISBN: 321223675
EAN: N/A
Year: 2006
Pages: 282

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net