1.6 - Software Coding Standards¶

From the very beginning of WebGL program development you should be using 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. And that is what we will do in these tutorials.

The example code in these tutorials follow good programming standards as defined in the hyperlinked documents below. Please use these coding standards as you develop your own WebGL programs. The main goal is to be consistent in your naming schemes.

The major recommendations from these coding standards are list 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 use 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>:

<!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. (The Pycharm IDE will do this for you.)
Use two-space indentation.
Use shorthand for conditional statements where appropriate: var results = (test === 5) ? alert(1) : alert(2);
The closing brace should be on the same indent as the original statement:
```
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 not be used in names.
- Plurals should not be used when assigning names.
- Comments should be used within reason.
- Use YUIDoc to document functions.
```
/**
 * 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¶

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.
Put the WebGL version number at the top of each shader. #version 103
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.

Next Section - 2.1 - Introduction to Languages and Tools