1.8 - Software Coding Standards¶

From the very beginning of WebGL program development you need to use good programming standards. This is a “chicken or the egg” problem. How can you discuss coding standards before you know a language? You can’t really, but discussing coding standards after you learn a programming language is too late. So the answer is to discuss coding standards before, during, and after you learn a new language.

All of the example code in this textbook follows good programming standards as defined in the hyperlinked documents below. Please use these coding standards as you develop your own WebGL programs.

The major recommendations from these coding standards are listed below for conciseness. If you want the full rational for any of the rules, please refer to the original reference documents.

HTML Coding Standards¶

Always declare the document type as the first line in your document: <!doctype html>
Use lower case element names: <p>, <div>
Close all elements: <p> ... </p>
Close empty elements: <br />
Use lowercase attribute names: <div class="...">
Quote all attribute values for consistency: <div class="...">
Don’t include spaces around equal signs: <div class="...">
Try to avoid code lines longer than 80 characters.
For readability, add blank lines to separate large or logical code blocks.
For readability, add 2 spaces of indentation for code inside a parent element. Do not use TAB characters.
Always include a <html>, <head> and <body> tag.

Always include the language, character encoding, and title tags:

<!doctype html>
<html lang="en-US">
<head>
  <meta charset="UTF-8">
  <title>HTML5 Syntax and Coding Style</title>
</head>

Include appropriate comments: 
Use simple syntax for linking style sheets: <link rel="stylesheet" href="styles.css">
Use simple syntax for loading external scripts: <script src="myscript.js">
Use the same naming convention in HTML as JavaScript.
Always use lower case file names.
Use consistent file name extensions: .html, .css, .js, .frag, .vert, .obj, .mtl

Javascript Coding Standards¶

Always include "use strict"; to force the declaration of variables.
Avoid global variables whenever possible.
Use JSLint to check for errors and style issues. (Most IDE’s will do this for you, including Pycharm or WebStorm.)
Use two-space indentation.
Use shorthand for conditional statements where appropriate: var results = (test === 5) ? alert(1) : alert(2);
Closing braces should be on the same indent as the original statement. For example,
```
function func() {
  return {
    "name": "Batman"
  };
}
```
Naming conventions:
- Constructors start with a capital letter.
- Methods/functions start with a small letter.
- Methods/functions should use camel case. thisIsAnExample
- Variables should always use an underscore between words. this_is_an_example
- When appropriate, include the variable type in the name. value_list
- Element ID’s and class names should always use an underscore between words.
- Private methods should use a leading underscore to separate them from public methods.
- Abbreviations should be avoided.
- Plurals should not be used when assigning names.
- Comments should be included within reason.
- Use YUIDoc to document functions. For example,
```
/**
 * Reverse a string
 *
 * @param  {String} input_string String to reverse
 * @return {String} The reversed string
 */
function reverseString(input_string) {
  // ...
  return output_string;
};
```

GLSL Coding Standards¶

Put the GLSL version number at the top of each shader. (E.g, #version 103 means version 1.03)
Include appropriate comments in your code.
- Write //VERTEX SHADER at the top of your vertex shader.
- Write //FRAGMENT SHADER at the top of your fragment shader.
Avoid “all-in-one-shaders”. Write separate shaders as needed.

Refer back to this page as needed. Consistency in coding is important.

Glossary¶

coding standard: a set of rules that make programming code easier to understand, easier to modify, and more cross-platform compatible.
HTML: hypertext markup language - a language for describing the contents of a web page
JavaScript: a programming language for manipulating a web page after it has been downloaded to a client’s computer. JavaScript is not related to Java.
GLSL: graphics language shader language - a programming language used in the graphics pipeline to manipulate graphics data.

Self-Assessments¶

<!doctype html>
Correct, this describes what kind of data the file contains.
<head>
Incorrect, the <head> tag describes a web page's meta-data, not the file's entire contents.
<body>
Incorrect, the <body> tag describes a web page's visible elements.
<title>
Incorrect, the <title> tag gives a title string to the web page, which is typically displayed by a browser in its tab name.

example_file_name.js
Correct, use only lower case in file names. (For some operating systems, Abc.txt and abc.txt are different files, while for other operating systems, they are the same file.)
Example.html
Incorrect. Don't use upper case letters.
AGoodFileName.vert
Incorrect. Don't use upper case letters.
anExample_to_follow.xyz
Incorrect, because it mixes CamelCase and underscores, and it has an unrecognized file extension.

MyExample

class
Correct. Class names always begin with a capital letter.
variable
Incorrect. Variable names use lower only case letters and no CamelCase.
function
Incorrect. Functions should always start with a small letter.
private function
Incorrect. Private functions should always start with an underscore, _.

apples_array

an array
Correct, since the type is included in the name.
a single float
Incorrect.
a string
Incorrect.
an integer
Incorrect.

Next Section - 1.9 - Summary of this Textbook