HTML Coding Guidelines
Like this article? We recommend
Like this article? We recommend
Like this article? We recommend
The previous article in this series continued our introduction to HTML in Web applications with a discussion of the core elements of both HTML and Web applications in general. This article explores the use of HTML in more detail, presenting a number of coding and design guidelines that will help improve the maintainability and reusability of HTML code.
The result of a successful software-development project is a body of source code that represents the solution to a business need at a specific point in time. As conditions change, this solution might need to be updated for it to continue to meet business needs. In addition, software development is an expensive undertaking. As with any business resource, it is desirable to leverage source code as fully as possible to obtain maximum value.
Leaders of software-development projects should keep these considerations in mind while planning and executing the project. Maximizing the maintainability and reusability of source code is the key to obtaining full value from software-development expenditures.
The previous two articles presented you with a clearer picture of what elements make up a Web application and the role of HTML in these applications. Now we will turn our attention to the HTML code itself. This section presents some general guidelines for coding HTML that will help improve readability, maintainability, and code reuse.
Design Guidelines
The first and best opportunity for improving HTML code comes during the planning stage. When designing the Web application, consider the following general guidelines for organizing internal document structure and the HTML code:
- Plan ahead.
- Encapsulate formatting/styles.
- Use include files wisely.
- Serve HTML directly.
- Understand the HTML document structure.
- Use metatags.
Plan Ahead
Possibly one of the most important things that you can do to maximize the maintainability and reusability of HTML code is to plan ahead. Establish standards for coding style and practices, document these standards, and then stick with them.
Standards for coding style often include rules about the use of capitalization, indentation, naming, line length, and comments. Standards for programming practice might include rules about the use of external files, source code control, testing, documentation, and reporting.
Encapsulate Formatting/Styles
The Web developer can explicitly specify many display characteristics of HTML elements, including fonts, colors, and positioning, by setting the element's style property. For example, the following code specifies that the paragraph element should be displayed at a position 10 pixels from the left of the browser window and 20 pixels from the top. It further specifies that the browser should use 24-point Verdana font and should display the element in blue.
<p style="position:absolute;
pixel-left:10px;pixel-top:20px;
font-family:Verdana;font-size:24pt;
color:Blue">Some text</p>
The inline style shown in the previous code demonstrates one way in which the developer can use Cascading Style Sheets (CSS) to specify characteristics of HTML elements. CSS also allows the developer to encapsulate styles within the document and even in separate files. We will explore CSS in more detail in later articles in this series, but, as a general guideline, it is better to encapsulate styles whenever possible rather than to use inline styles. The reason is manageability. When the specifications for a style change, it is much easier to change it in one style sheet than to change it in every element that applies the style.
Use Include Files Wisely
The developer can also encapsulate HTML and script code in files separately from the main document. The #include directive will cause the specified external file to be inserted into the current page at that point. For example, the following code includes an external file whose name implies that it contains JavaScript functions for data or input validation:
<!-- #include file="../include/validation.js" -->
Include files are often used to maintain script code with similar functions grouped together. This is a good approach to application design to enhance code reusability. The same include file might be used by multiple pages in several different applications.
However, it is important to remember that the entire external file will be included; there is no mechanism to include only the portion of HTML or script code actually used by the current page. Therefore, it is important to set up include files wisely, to minimize the inclusion of extraneous code. The benefits gained through the use of included external files will be explored further in later articles on client-side scripting.
Serve HTML Code Directly
Many modern Web applications are data-driven. In these applications, large parts of both the server-side and the client-side code are generated programmatically at runtime. While this is the nature of a data-driven Web application, it can make source code much harder to read and reuse.
Whenever possible, use HTML code directly in .HTM or .HTML files, instead of writing HTML-formatted strings from scripts. For example, look at the following code for the start tag of a form element:
<form action="input.asp" name="frmDataInput" language="JavaScript" onsubmit='return validate();'>
Now compare the following code that uses the ASP Response.Write method to generate the same HTML code. It is much more difficult to read and maintain than the direct HTML:
<% Response.Write "<form action=""input.asp""" & vbCrLf Response.Write "name=""frmDataInput""" & vbCrLf Response.Write "language=""JavaScript""" & vbCrLf Response.Write "onsubmit='return validate();'>" & vbCrLf %>
Besides manageability, there are other reasons to maintain HTML code in straight HTML source files. One of these is that development tools for HTML code work best on HTML source. For example, syntax highlighting will usually not work for the HTML code in the previous code listing. Another reason is to reduce the multiple nested quotes that commonly crop up when generating HTML from script.
However, there are times when the developer must use script to dynamically generate HTML that reflects the current state of the system. However, when it is an option, straight HTML is much more manageable. If you must generate HTML from script, then at least have the script write out the HTML code with good formatting so that the generated source code is easier to read and understand.
HTML Document Structure
An HTML document consists of two distinct sections: the head and the body. The Web server also prepends an informational header to the text stream for evaluation by the browser. The Web developer can make the application better structured by using the HTML document structure appropriately.
The <html></html> tag pair delimits the entire content of the Web page and signals that the document is in HTML format. There are two subsections in the document: the head, delimited by the <head></head> tag pair, and the body, enclosed within the <body></body> tags. Listing 1 illustrates the structure of an HTML document.
Listing 1: HTML Document Structure
<html> <head> <title>Document Title</title> <meta name="Description" content="HTML document sample with metadata"> <meta name="Keywords" content="document structure, section, metadata"> </head> <body> </body> </html>
The head section of an HTML document has one required subsection, the title. Delimited by the <title></title> tag pair, this element is usually used for a short descriptive document title. Other than the title, the head section does not contain content intended for regular display on the browser. Instead, it provides a place to organize information about the document itself and resources used to display the content, such as scripts and style sheets.
Information about the document itself is an example of metadata (see the sidebar entitled "Metadata"). Metadata for HTML documents is included in the head section using the <meta> tag, which is discussed further in the next section.
Metadata
Metadata is often defined as "data about data." A better description is information that describes or characterizes the data—both its content and container. Like the first paragraph of a well-crafted news story, metadata answers the questions who, what, where, when, why, and how.
Use Metatags
HTML <meta> tags are used to delimit information about the HTML document—for example, information about the document author and copyright. Keywords and description fields can be used to provide an index of the content and code in the document.