Administrative Computing Developer Resources
 
S A P Development Standards Web Development Standards Quality Assurance Glossary    

Rule #5: Less than two. Call includes from the main web page.

An include in SSI, businessHTML, or other HTML document is not the same as the C++ include statement or the Java import statement. Application developers misinterpret the use of the include keyword in presentation layer development because of their familiarity with other programming environments. In a web front-end, the fundamental purpose of an include is to reuse a static chunk of HTML across multiple web pages. You should do your best to adhere to this purpose.

Includes never call other includes.

All web scripting languages let you package code in an external file and then "include" into the main web page. Import techniques can be combined in very confusing ways, so encourage simplification by making sure that imported, client-side source code is always less than two steps away from the main file. This relates to static HTML, JavaScript, and CSS, and is independent of whether the method of inclusion is JavaScript src, CSS <link />, or a server-side include statement.

Server-side includes used for static HTML templating should not contain additional include statements. That level of complexity is not justified by simple templating needs.

If you are an application developer, server-side scripting languages provide import or require statements for loading PHP, Perl, or JSP libraries to reuse in your own server-side procedures. The rules do not apply to that situation. In addition, the businessHTML include statement is multipurpose; it can be used either like a normal server-side include, or like a Perl template. Apply this rule to businessHTML where its function is the former.

A call to a procedure is less than two steps away from the procedure itself.

When you use included procedures, you have to make it easy for another programmer to find the files or programs where they are stored. You have some options that can sometimes be used in combination:

  1. All calls to procedures included by external files should happen in the main page's code.
  2. Keep a library isolated in a directory with the same name as the title of the library. For instance, keep the S.U.I.T JavaScript library in a /suit/ subdirectory on the web server. That way, references to suit.ThisWidget() and suit.ThatWidget() can be easily tracked by another programmer via the directory name.
  3. Name the include source file similar to the procedure or variable it contains. Then you can use something from an include, and quickly find the included source by looking at the main web page. For instance, a procedure named ThisWidget() would be in the file ThisWidget.inc.
M I T
I S and T

© Copyright 2002 by the Massachusetts Institute of Technology, Cambridge, MA, USA.
View the full Copyright Notice and Disclaimer.