<commit_before># Coding Guide

Cesium is one of the largest JavaScript codebases in the world.  Since its start, we have maintained a high standard for code quality, which has made the codebase easier to work with for both new and experienced contributors.  We hope you find the codebase to be clean and consistent.

In addition to describing typical coding conventions, this guide also covers best practices for design, maintainability, and performance.

:art: The color palette icon indicates a design tip.

:house: The house icon indicates a maintainability tip.

:speedboat: The speedboat indicates a performance tip.

This guide can be summarized as _make new code similar to existing code_.

_TODO: TOC_

## Naming

_TODO_

## GLSL

### Naming

* GLSL files end with `.glsl` and are in the [Shaders](https://github.com/AnalyticalGraphicsInc/cesium/tree/master/Source/Shaders) directory.
* Files for vertex shaders have a `VS` suffix; fragment shaders have an `FS` suffix.  For example: `BillboardCollectionVS.glsl` and `BillboardCollectionFS.glsl`.
* Generally, identifiers, such as functions and variables, use `camelCase`.
* Cesium built-in identifiers start with `czm_`, for example, [czm_material](https://github.com/AnalyticalGraphicsInc/cesium/blob/master/Source/Shaders/Builtin/Structs/material.glsl).  Files have the same name without the `czm_` prefix, e.g., `material.glsl`.
* Varyings start with `v_`, e.g., `varying vec2 v_textureCoordinates;`.
* Uniforms start with `u_`, e.g., `uniform sampler2D u_atlas;`.
* An `EC` suffix indicates the point or vector is in eye coordiantes, e.g.,
```glsl
varying vec3 v_positionEC;
// ...
v_positionEC = (czm_modelViewRelativeToEye * p).xyz;
```
* When [GPU RTE](http://blogs.agi.com/insight3d/index.php/2008/09/03/precisions-precisions/) is used `High` and `Low` suffixes define the high and low bits, respectively, e.g.,
```glsl
attribute vec3 position3DHigh;
attribute vec3 position3DLow;
```
* 2D texture coordinates are `s` and `t`, not `u` and `v`, e.g., `attribute vec2 st;`.

### Formatting

* Use the same formatting as JavaScript, except put `{` on a new line, e.g.,
```glsl
struct czm_ray
{
    vec3 origin;
    vec3 direction;
};
```

### Performance

* :speedboat: Compute expensive value as least frequently as possible, e.g., prefer computing a value in JavaScript and passing it in a uniform to redundantly computing the same value per-vertex.  Likewise, prefer to compute a value per-vertex and pass a varying, instead of computing per-fragment when possible.
* :speedboat: Use `discard` sparingly since it disables early-z GPU optimizations.

## Resources

See Section 4.1 to 4.3 of [Getting Serious with JavaScript](http://webglinsights.github.io/downloads/WebGL-Insights-Chapter-4.pdf) by Cesium contributors <NAME> and <NAME> in _WebGL Insights_ for a deeper coverage of modules and performance.

Watch [From Console to Chrome](https://www.youtube.com/watch?v=XAqIpGU8ZZk) by <NAME> for even deeper performance coverage.

---

_TODO: use defined_
_TODO: destroy pattern_
_TODO: promises_
_TODO: web workers_
_TODO: comment why, not what_
_TODO: create WebGL resources in update()_
_TODO: Pascal case for classes, camel case for functions_
_TODO: passing options to functions_
_TODO: constructors vs from functions_
_TODO: prototype vs. non prototype function_
_TODO: implement equals_
_TODO: underscore for private_
_TODO: file-scope functions_
_TOOD: compare with ===_
_TODO: property getters_
_TODO: when to throw DeveloperError_
_TODO: use includeStart for exceptions_
_TODO: only make public if useful_
_TODO: create enums with freezeObject_
_TODO: loose coupling, high cohesion_
_TODO: Don't merge code with TODO, PERFORMANCE_IDEA is OK_
_TODO: declare variables where they are used, even though they are hoisted_
_TODO: hoisting functions is OK_
_TOOD: constants with freezeObject_
_TODO: do not dynamically add members_
_TODO: scratch variables, results parameters, avoid GC_
_TODO: smaller functions get optimized_
_TODO: single return to inline_
_TODO: profiling/debugging tools - separate guide?_
_TODO: Cesium stack screenshot like this http://cesiumjs.org/2015/05/26/Graphics-Tech-in-Cesium-Stack/_
_TODO: UI_
_TODO: remove old wiki guide_
<commit_msg>Naming<commit_after># Coding Guide

Cesium is one of the largest JavaScript codebases in the world.  Since its start, we have maintained a high standard for code quality, which has made the codebase easier to work with for both new and experienced contributors.  We hope you find the codebase to be clean and consistent.

In addition to describing typical coding conventions, this guide also covers best practices for design, maintainability, and performance.

:art: The color palette icon indicates a design tip.

:house: The house icon indicates a maintainability tip.

:speedboat: The speedboat indicates a performance tip.

This guide can be summarized as _make new code similar to existing code_.

_TODO: TOC_

## Naming

* Directory names are `PascalCase`, e.g., `Source/Scene`.
* Constructor functions are `PascalCase`, e.g., `Cartesian3`.
* Functions are `camelCase`, e.g., `defaultValue`, `Cartesian3.equalsEpsilon`.
* Files end in `.js` and have the same name as the identifier, e.g., `Cartesian3.js` and `defaultValue.js`.
* Variables, including class members, are `camelCase`, e.g.,
```javascript
this.minimumPixelSize = 1.0;

var bufferViews = model.gltf.bufferViews;
```
* Private members start with an underscore, e.g.,
```javascript
this._canvas = canvas;
```
* Constants are in uppercase with underscores, e.g., `Cartesian3.UNIT_X = freezeObject(new Cartesian3(1.0, 0.0, 0.0));`.
* Avoid abbreviations in public identifiers unless the full name is prohibitively cumbersome, e.g., use ` Cartesian3.maximumComponent()` not ` Cartesian3.maxComponent()`, but use `Ellipsoid.WGS84` instead of `Ellipsoid.WORLD_GEODETIC_SYSTEM_1984`.
* Prefer short and descriptive names for local variables, e.g., if a function has only one length variable, prefer
```javascript
var length = primitives.length;
```
instead of
```javascript
var primitivesLength = primitives.length;
```

_TODO: make the following links_

More naming conventions are introduced below along with their design pattern, e.g., options parameters, result parameters, from constructors, and scratch variables.

## GLSL

### Naming

* GLSL files end with `.glsl` and are in the [Shaders](https://github.com/AnalyticalGraphicsInc/cesium/tree/master/Source/Shaders) directory.
* Files for vertex shaders have a `VS` suffix; fragment shaders have an `FS` suffix.  For example: `BillboardCollectionVS.glsl` and `BillboardCollectionFS.glsl`.
* Generally, identifiers, such as functions and variables, use `camelCase`.
* Cesium built-in identifiers start with `czm_`, for example, [czm_material](https://github.com/AnalyticalGraphicsInc/cesium/blob/master/Source/Shaders/Builtin/Structs/material.glsl).  Files have the same name without the `czm_` prefix, e.g., `material.glsl`.
* Varyings start with `v_`, e.g., `varying vec2 v_textureCoordinates;`.
* Uniforms start with `u_`, e.g., `uniform sampler2D u_atlas;`.
* An `EC` suffix indicates the point or vector is in eye coordiantes, e.g.,
```glsl
varying vec3 v_positionEC;
// ...
v_positionEC = (czm_modelViewRelativeToEye * p).xyz;
```
* When [GPU RTE](http://blogs.agi.com/insight3d/index.php/2008/09/03/precisions-precisions/) is used `High` and `Low` suffixes define the high and low bits, respectively, e.g.,
```glsl
attribute vec3 position3DHigh;
attribute vec3 position3DLow;
```
* 2D texture coordinates are `s` and `t`, not `u` and `v`, e.g., `attribute vec2 st;`.

### Formatting

* Use the same formatting as JavaScript, except put `{` on a new line, e.g.,
```glsl
struct czm_ray
{
    vec3 origin;
    vec3 direction;
};
```

### Performance

* :speedboat: Compute expensive value as least frequently as possible, e.g., prefer computing a value in JavaScript and passing it in a uniform to redundantly computing the same value per-vertex.  Likewise, prefer to compute a value per-vertex and pass a varying, instead of computing per-fragment when possible.
* :speedboat: Use `discard` sparingly since it disables early-z GPU optimizations.

## Resources

See Section 4.1 to 4.3 of [Getting Serious with JavaScript](http://webglinsights.github.io/downloads/WebGL-Insights-Chapter-4.pdf) by Cesium contributors <NAME> and <NAME> in _WebGL Insights_ for a deeper coverage of modules and performance.

Watch [From Console to Chrome](https://www.youtube.com/watch?v=XAqIpGU8ZZk) by <NAME> for even deeper performance coverage.

---

_TODO: use ()_
_TODO: use defined_
_TODO: destroy pattern_
_TODO: promises_
_TODO: web workers_
_TODO: comment why, not what_
_TODO: create WebGL resources in update()_
_TODO: shadow values_
_TODO: passing options to functions_
_TODO: constructors vs from functions_
_TODO: prototype vs. non prototype function_
_TODO: implement equals_
_TODO: underscore for private_
_TODO: file-scope functions_
_TOOD: compare with ===_
_TODO: property getters_
_TODO: when to throw DeveloperError_
_TODO: use includeStart for exceptions_
_TODO: only make public if useful_
_TODO: create enums with freezeObject_
_TODO: loose coupling, high cohesion_
_TODO: Don't merge code with TODO, PERFORMANCE_IDEA is OK_
_TODO: declare variables where they are used, even though they are hoisted_
_TODO: hoisting functions is OK_
_TOOD: constants with freezeObject_
_TODO: do not dynamically add members_
_TODO: scratch variables, results parameters, avoid GC_
_TODO: smaller functions get optimized_
_TODO: single return to inline_
_TODO: profiling/debugging tools - separate guide?_
_TODO: Cesium stack screenshot like this http://cesiumjs.org/2015/05/26/Graphics-Tech-in-Cesium-Stack/_
_TODO: UI_
_TODO: css_
_TODO: remove old wiki guide_

{'fraction_non_alphanumeric': 0.09028839294813003, 'fraction_numerical': 0.009069601548965658, 'mean_word_length': 4.962332928311057, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 9, 'https://': 6, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2005271', 'n_tokens_mistral': 3084, 'n_tokens_neox': 2940, 'n_words': 1195}