Naming Conventions

How you name items will have great impact on the maintenance, readability, and usability of your code. Not only do individual languages and database systems have their own naming requirements for tables, variables, code pages, and so on, but you should also set your own requirements and publish them within the IT department as your company's Naming Convention List. Once you have a uniform naming scheme in place, you'll find it's easier for developers to work on one another's code when necessary and be able to interpret the meaning of the entire code base much faster. New recruits to the organization will learn your systems faster as well.

Again, we're going to give you a few guidelines to follow. Our choices for naming conventions won't fit everyone, so adapt what you learn to your needs. But, above all, be consistent in the application of your own schema.

Naming Variables

You can assign meaningful names to your variables in many ways. In fact, you'll find developers defending their naming scheme against another any time you bring up naming conventions because, naturally, their way makes more sense to them. Well, you should strive to follow certain guidelines, no matter how you name your variables.

Charles Simonyi, a Microsoft programmer for many years, created a schema for naming variables and other data items that has propagated throughout the technical world. It's affectionately known as "Hungarian" notation, apparently for two reasons: Simonyi is Hungarian, and the schema makes your variables look as though they're written in a non-English language. Although you probably won't want to adopt Simonyi's full schema, we recommend that you make a variation of that schema part of your standard coding practice policy.

Tip 

Interested in reading more about Charles Simonyi's "Hungarian" notation? Check out the ten-page article on Microsoft's site at: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnvsgen/ html/HungaNotat.asp.

Our version of Hungarian notation that works quite well for us in naming variables is as follows: Combine whole words to form your variable names so that the name indicates exactly what the variable contains; don't use cryptic variable names. Some good examples are cFirstName, dDateSold, lHasCaptain, and nGrandTotal.

  • Proper-case significant words within your variables. For example, FirstName is combined from two whole, stand-alone words to form the variable name.

  • Many developers like to indicate the type of their variables within the name. For example you might use a naming scheme such as the following:

    aUserList

    Indicates an array called UserList

    cFirstName

    Indicates a character variable called FirstName

    lHasCaptain

    Indicates a logical variable named HasCaptain

    nGrandTotal

    Indicates a numeric variable called GrandTotal

  • There is a potential drawback to typing your variables within their names: if the datatype of the variable should change, you'll need to rename the variable in order to remain consistent. With global search and replace, though, this isn't such a big deal. We find the benefit of having the variable typed in its name well worth the potential cost of having to perform a global search and replace on the codebase. Decide on a scheme for your variable types, and apply it accordingly to your variable names. This type of identification helps in understanding code, especially if you're modifying code someone else wrote.

  • Depending on the language in which you're developing, you might want to go so far as to add prefixes or suffixes to your variables to indicate their content types. For example, str_User for a structure variable or sn_LoggedIn for a session variable.

  • You might want to include scope, as well: g_VarName for global, l_varName for local, and so forth.

  • Don't go overboard with the naming prefixes, though. We know a developer who had so many prefixes that his prefix list was always longer than his variable names.

  • When writing JavaScript code, you might want to follow the convention set forth by Dream- weaver itself: lowercase the first word of your variable names, but use proper casing (or an initial capital letter) for each word thereafter, such as myGetDate.

Whenever you're naming constants, you'll want to keep them in all uppercase letters. This makes the constant stand out clearly. You might also want to separate the words within constants by an underscore, to distinguish them even more clearly from a variable. For example, DAYS_UNTIL_ EXPIRATION certainly makes more of an impact than nDaysUntilExpiration.

Name Boolean variables in such a way that they imply a logical true/false or yes/no answer. For example, lIsRegistered and lHasPaid lend themselves to a simple yes/no answer.

However you choose to name your variables, be consistent and be clear. Make certain that the developers in your organization understand the meanings of the schema you adopt. And make certain that everyone follows the same naming conventions.

Naming Data Tables

Just as in naming variables, following a few guidelines for naming data tables can save you time and confusion during your development process. Although you won't be "typing" your data tables with prefixes, you can certainly indicate the use of the data within the table name. For example, names such as "Employee," "RegisteredUser," and "ProductOnOrder" indicate the type of data in the table.

Naming linking tables can sometimes be a confusing process, since the link table contains keys from two or more tables. You could add the suffix _omLink to the end of the table for a one-to-many link table or _mmLink for many-to-many. (For more information about linking tables, see Chapter 5.)

Another convention you'll have to weigh within your organization is whether to name tables using plurals. We recommend that you do not use plurals in anything. In a multideveloper environment, plurals tend to cause more confusion than they're worth. Invariably, someone will forget to add the "s" for the Players table in a query, only to have to go back and debug the problem once the query fails. Plurals just aren't good in names. (On the other hand, if you must use plurals, make sure you do use them in every table name.)

Naming Data Columns

You can also make your development life easier if you adhere to a few guidelines for naming data columns and database field names. Again, you want to avoid plurals. Player or Players-it seems trivial just reading about it, but when you're in the midst of coding, you don't want to break your stride by having to look up the spelling of a table name.

Also, it's not a good idea to repeat the table name in the field name. For example, you shouldn't have a table named Player and a field named PlayerFirstName. The fact that the field resides in the Player table is sufficient to indicate that FirstName relates to Player.

Earlier, we mentioned naming your variables so that you know the datatype by reading the variable name. Don't adhere to this convention when naming table fields. It's not uncommon for table fields to change datatypes during the first phases of development of any system. Renaming table fields probably won't be as easy as renaming variables, since you'll have queries, forms and the like on which to perform a global search and replace.

You might want to separate your table field names with an underscore. That is, separate complete words in the name with an underscore, but save this practice for data columns. If you do so, you'll always know just by looking at the name which you're referring to-the field or the variable.

Note 

Note If you name your data columns-or table fields-identically to variables used in your pages, Dreamweaver MX will try to automatically bind your variables when you use Server Behaviors. Even though this default behavior is nice, you might want to forgo this nicety for clearer, easily understood code.

A Few Other Naming Guidelines

You can establish guidelines for anything that you must name in coding circles, so we'd like to give you a few more pointers on doing so. Although we certainly can't cover every possible item, using the following you should get an idea of how to name the entities we haven't mentioned.

  • You can preface the name of a generic object with a lowercase o or obj, for example, oComment or objMemo.

  • For connection objects, use conn plus the database name, such as connEmployee.

  • You might want to preface query variables with qry, for example, qryGetAllUserInfo and recordsets with rst, for example, rstAllWithProduct.

  • Since queries and stored procedures actually perform some type of action, you should probably include that action in the object's name, for example, qryInsertUserInfo or spGetSalesSummary.

  • Don't use spaces in table or field names. Spaces can cause problems with some tools, such as external data access tools.

  • Do not use reserved words (words that are actual commands) to name your tables. This can cause problems with the language or database you're using.

HTML Guidelines

When coding HTML or any program files, either by hand or using Dreamweaver MX, there are a few guidelines you can follow to make your HTML play nicely with browsers, servers, and users. The following guidelines are simply a starting point for your own list of HTML rules, so, as always, take what we show you and adapt it to your working environment. But above all, be consistent.

Filenames

There are many different types of web servers, and many of them are picky about filenames and, of all things, the case of filenames. If you follow these few simple rules, though, your filenames should not cause trouble.

  • Don't use spaces in filenames. Spaces can cause all sorts of problems with servers, browsers, file listings, and so forth, since they can confuse a system into thinking the filename has ended.

  • Use underscores to make your filenames clear and readable. Separate whole words with underscores, for example, show_player_data.htm.

  • Don't use uppercase in filenames. Some Unix versions have problems with uppercase names, and some operating systems are case-sensitive. You can avoid both traps by simply using lower- case in all filenames. Besides, uppercase can make directory listings difficult to read.

File Components

Certain components of your HTML files can benefit if you apply a few consistent rules to them. Not only will the rules make your code clearer and easier to understand, but you'll find it functions better as well.

  • Titles-any page that is displayed to a user should have a title. Titles are a good way to inform your users of where they are or what they should do in a site. Plus, some search engines use the title text in their data. (You don't need to give pages that aren't seen by a user, such as action pages, titles.)

  • Meta tags-any page that you'd like a user to find in a search engine should have a meta tag list. Many search engines use the meta tags to categorize the pages they encounter, so a properly defined meta tag list could be very beneficial to your site traffic.

  • Links-when linking to other pages within your site, you probably want to use relative paths as opposed to fully qualified domain names. If you're wanting to display an image stored in your image directory, you shouldn't use <img src="/books/1/127/1/html/2/http://your.site.com/images/ imagename">, since that kind of link causes more work for your server. Instead, use a relative path in the img tag such as <img src="/books/1/127/1/html/2/./images/imagename">.

  • Tables-in order to make tables display properly in all browsers, you should include non- breaking spaces in blank table cells. The &nbsp; character will put a blank space in the table. Some browsers won't properly display the borders of tables if the cell is empty. (You may see the non-breaking space character refered to as a "non-blanking" space. The World Wide Web Consortium [www.w3c.org], the ruling body of HTML standards, officially calls it the "non-breaking space.")

HTML Usability Rules

And of course, we have a few general rules we'd like to share.

Design for 800 × 600 screens. Most monitors today are designed to work better at a resolution of at least 800 × 600. (The optimal resolution for 17-inch monitors is 1024 × 768, but many users like the bigger type that an 800 × 600 setting on a 17-inch monitor provides.) Therefore, design your web pages with this resolution in mind.

Keep in mind while working on your high-speed corporate Internet connection that many users still rely on dial-up modems for their Internet connection, both at work and at home. Think about this before you fill a page full of heavy graphics. You don't want to chase off a potential customer by forcing them to wait a long time to load your site's pages.

Design for Netscape 4.5 and Internet Explorer 5 and later browsers. (Okay, let the controversy fly.) Many developers and companies proclaim that you should develop for version 4 browsers and later. Browsers are still free, and new versions are released all the time. Encourage your users to update their browsers by testing your code for browser versions earlier than Internet Explorer 5 (or Netscape 4.5), and guide users to the proper update pages if necessary. Of course, you don't want to alienate anyone, so test your code for version 4 compliancy and perhaps offer solutions to those using older browsers. (Yes, other browsers are available, as well, such as Opera, Mozilla, and so forth. These browsers take the two major browsers' features into consideration and operate in a similar manner.)

As features and options in HTML change and grow thanks to new technologies, new standards, and the like, web-usability standards may change. Although there are numerous books and articles on the best design rules, best usability rules, best user-interface rules, and best you-name-it rules, perhaps your best place to start looking for more information is the web itself. Check out Jakob Nielsen's site at www.useit.com. The irreverent among you will want to take a look at Web Pages That Suck, by Vincent Flanders and Michael Willis (Sybex, 1998) and Son of Web Pages That Suck, by Vincent Flanders and Dean Peters (Sybex, 2002). You can find Mr. Flanders' website at www.webpagesthatsuck.com. Another book you might want to obtain is Don't Make Me Think, by Steve Krug and Roger Black (Que, 2000).

Accessibility

Any site that hopes to reach all audiences and all peoples must make sure that its information is accessible to everyone-that includes people with disabilities that hinder or prevent their ability to gain access to your site's information. Unfortunately, those with disabilities are frequently overlooked when it comes to website design and construction. To remedy this situation, the World Wide Web Consortium's (W3C) Web Accessibility Initiative is striving to educate and urge the development community to apply its accessibility standards to websites.

With Internet access now reaching all aspects of American society and even proliferating in countries such as China whose control over Internet access was legendary, accessibility is becoming even more an issue. Millions of current and potential web users have disabilities and require sites that will work with hardware such as site readers, voice recognition systems, magnifiers, and so forth.

Tip 

You can read more about the W3C's Web Accessibility Initiative and find a complete list of guidelines at www.w3.org/WAI/.

Web-accessible sites use the ALT tag on all images and animations; provide captioning and transcripts of audio and video; use hyperlink text that is sensible and descriptive when read aloud; provide style sheets that a user can override; and use many HTML 4.01 tags (such as ACRONYM for spelling out the title of an acronym for screen readers, for example, "World Wide Web" for WWW).

The W3C is offering a Quick Tips card for free, in quantities up to 500, to help spread the word about the Web Accessibility Initiative. You can also print a sample of the card from their website at www.w3.org/WAI/References/QuickTips. This Quick Tip card is available in several translations, including English, Danish, Dutch, Finnish, French, German, Italian, Norwegian, Portuguese, Spanish, and Swedish and also in Braille.Dreamweaver MX can help you make your site compliant with web accessibility guidelines. When you turn on Accessibility Options in the Preferences window (choose Edit â Preferences â Accessibility), Dreamweaver MX lets you activate features about specific accessibility tags and settings related to various HTML objects. Figure 3.1 shows you the Accessibility options you can activate. As you can see, we've chosen almost all the options so that we can start making our sites W3C WAI compliant. (We haven't chosen Use Large Fonts because it doesn't apply to our web pages. This option causes Dreamweaver MX to display its fonts in a larger size during design time.)

click to expand
Figure 3.1: Another strength of Dreamweaver MX is its ability to guide you in making your websites compliant with the W3C Web Accessibility Initiative.

Once the Accessibility options are turned on, Dreamweaver MX will ask you for specific parameters related to making that option W3C WAI compliant whenever you add one of the activated options to a web page. For example, Figure 3.2 shows the options presented when you try to add a text field to a form after activating the Accessibility option for Form Objects.

click to expand
Figure 3.2: Dreamweaver MX asks for Accessibility components when you drop a text field onto a form.

Dreamweaver MX asks for features such as the type of label you want to use, an access key (hotkey), and so forth. One of the bonuses of the WAI recommendations is that web pages can now include features such as hotkeys. When you use the settings in Figure 3.2, Dreamweaver MX generates code similar to the following in a web page (we added the <u> tags around the access keys for formatting purposes):

<form name="form1" method="post" action="">   <label for="textfield">User <u>N</u>ame</label>    <input type="text" name="textfield" accesskey="N" tabindex="1" >    <br>   <br>   <label for="label2"><u>P</u>assword</label>   <input type="text" name="textfield2" accesskey="P" tabindex="2" >    </form>

The <label> tag allows the user to select the text box by either clicking the text box itself-which is the usual selection method-or clicking the label next to the text box, which is new functionality. This approach reduces the amount of precision needed to select a text box in order to enter data. The accesskey qualifier of the <input> tag is an HTML 4 tag that allows the user to press hotkeys to gain access to specific features. The results of this code is that the user can press Alt+N in a Windows environment to jump to the User Name field. Likewise, pressing Alt+P jumps to the Password field. This allows those unable to move a mouse to navigate a form with ease.



Mastering Dreamweaver MX Databases
Mastering Dreamweaver MX Databases
ISBN: 078214148X
EAN: 2147483647
Year: 2002
Pages: 214

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