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:
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. |