forked from WorldWindLabs/SpaceBirds
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathWebWorldWindDesignAndCodingGuidelines.html
executable file
·194 lines (188 loc) · 9.17 KB
/
WebWorldWindDesignAndCodingGuidelines.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
<!DOCTYPE html><!--
~ Copyright (C) 2014 United States Government as represented by the Administrator of the
~ National Aeronautics and Space Administration. All Rights Reserved.
-->
<!--$Id: WebWorldWindDesignAndCodingGuidelines.html 3127 2015-05-29 16:32:21Z tgaskins $-->
<html>
<head lang="en">
<meta charset="UTF-8">
<title>Web World Wind Design and Coding Guidelines</title>
</head>
<body>
<h2>General</h2>
<ul>
<li>
See the Web World Wind Requirements document for the product requirements.
</li>
<li>
The project's development IDE is WebStorm. The WebStorm configuration files for the project are checked in to
the code repository. They define within them dependencies and formatting rules.
</li>
<li>
The Module pattern is followed for all functionality. All JavaScript code is captured within a module. There is
only one global defined by Web World Wind, and that is the WorldWind singleton. It contains the constructors and
static functions used throughout the rest of the library.
</li>
<li>
RequireJS is used to support the Module pattern and to provide AMD. Every module participates in RequireJS/AMD.
</li>
<li>
Web World Wind never crashes the browser. Always catch exceptions at least at the highest entry point, e.g.,
event listeners and thread execution.
</li>
<li>
Variable and function names are clear, descriptive and easy to read. They are not labelled with a convention not
described in this document. Use whole words rather than abbreviations, e.g., "index" rather than "idx". Correct
all variable spelling warnings flagged by WebStorm. Add necessary ones to your dictionary.
</li>
<li>
There are no "private" properties or functions/methods in Web World Wind. Assume that a module extender will
need access to all variables and functions of the module.
</li>
<li>
Third party libraries are used minimally and strong justification is required for their use. Any usage of third
party libraries must be agreed upon among the team and incorporated into the build system.
</li>
<li>
Protect WebGL state within a rendering unit, such as a layer, by bracketing state changes within exception
handlers. The goal is to isolate any WebGL state changes to the rendering unit, both when the unit succeeds and
when it fails.
</li>
<li>
A rendering unit assumes that the WebGL state is entirely at its default value when the rendering unit is given
control. The full WebGL state must be restored before the rendering unit releases control.
</li>
<li>
Web World Wind is designed such that the right things just happen once things are set up. The effect of
something going wrong is benign. Avoiding micromanagement of state and code brittleness. For example, layers
fork off retrieval of data but they don't try to keep track of these retrievals. If the retrieval succeeds then
the data will be available the next time the layer looks for it. If it's not available at that point then the
layer will simply ask for it again.
</li>
<li>
All code uses the JavaScript "use strict" directive.
</li>
<li>
WebStorm flags code errors and warnings as you write it. The errors are indicated by red and yellow markers in
the right margin of a module's editor window. When a module is checked in there should be no red flags and all
yellow flags should be addressed to the extent possible. Use F2 in WebStorm to move among errors and warnings.
Strive to have no warnings or spelling errors. In this case the square at the top of the right margin will be
dark green. (Light green indicates that there are spelling errors.)
</li>
<li>
The system is designed such that memory allocation and usage is minimized by both the system and its
applications. To that end many methods that compute and return a value of type other than Number accept a
"result" argument in which to return the computed value. When that argument exists, validate that it is non-null
and defined. The result argument is typically uses as the return value of the function.
</li>
</ul>
<h2>Exceptions</h2>
<ul>
<li>
WW objects pass exceptions through to the application unless there's good
reactive/corrective behavior that can be applied within WW.
</li>
<li>
Log any exceptions prior to throwing them. Use the same message for the log as for the exception. Use
pre-defined logger messages (see Logger) when possible. Pre-define in Logger those messages expected to be used
more than a few places.
</li>
<li>
Ensure all exception messages are descriptive and helpful, but keep them short.
</li>
<li>
"Public" functions validate their arguments and throw the appropriate exception, typically ArgumentError,
and identify the exception message the parameter name and the problem -- null, out of range, etc. Validation
is a necessary part of the implementation; code should not be checked in without it.
</li>
<li>
"Protected" methods whose calling client can't be trusted validate their arguments and throw an appropriate
exception.
</li>
<li>
When validating arguments, do not validate for type. Just validate non-Number arguments for existence and
appropriateness to the function. Validate arrays for sufficient length when the necessary length is known
a priori.
</li>
<li>
The audience for exceptions is not primarily the user of the client program, but the application or World Wind
developer. Throw exceptions that would let them know immediately that they're using faulty logic or data.
</li>
</ul>
<h2>Code Formatting</h2>
<ul>
<li>
All Web World Wind code follows the same style and conventions and looks the same in style and format.
</li>
<li>
Web World Wind code is heavily commented. The comments describe both the what and how of a block of code.
</li>
<li>
Web World Wind variable and function names are descriptive.
</li>
<li>
World Wind follows the coding conventions described in Chapter 2 of the book <em>JavaScript Patterns</em>. These
conventions are encoded in the WebStorm project files.
</li>
<li>
Line length is 120 characters and indentation widths are 4 characters.
</li>
<li>
Variable and function names use camel case. The exception is constructors, which capitalize their first letter.
Constants are in all upper case with words separated by underscores.
</li>
<li>
White space is preferred over packing code into a small space. Use white space liberally. Separate functional
blocks of code with vertical white space. Think of code within a function as a sequence of paragraphs and
separate each with a blank line.
</li>
<li>
Set up WebStorm to insert the standard copyright message into new code files.
<li>
Use the subversion Id keyword and be sure that it's used at the top of the file. When creating a new file, the
Id subversion keyword has to be explicitly set via Version Control --> Set Property --> Property name:
svn:keywords, and the term Id included in the text box. (If the property is not included in this list then
Subversion doesn't replace the property string when updating the file.)
</li>
</ul>
<h2>Documentation</h2>
<ul>
<li>
Documentation is generated by JSDoc.
</li>
<li>
Run JSDoc and review the results prior to checking in any code. It's a convenient check on documentation and
typing. Set up Grunt (GruntSetup.txt in the source repository) and use the jsdoc target.
</li>
<li>
Document all functions and properties. Mark those meant for internal use only as such.
</li>
<li>
Code isn't complete until the documentation is written. Write all documentation when you implement the function
or property. Don't wait until "later". Assume that you will never return to a module to "clean up".
</li>
<li>
Use present tense in all documentation. Examples are: "Indicates that ...", "Computes ...", "Returns ...". Do
not use terms like "Will compute" or "Will return".
</li>
<li>
Ensure that the type of all documented arguments and properties is specified in the documentation. For arrays,
use {Number[]} and {Vec3[]} and not simply {Array}.
</li>
<li>
Use correct capitalization and full sentences to document everything. All function, parameter and error
descriptions start with an upper case letter and end with a period.
</li>
<li>
Ensure that all method arguments, return values and exceptions are documented.
</li>
<li>
Use WebStorm to identify spelling mistakes in documentation. It will flag them with a wavy underline. Use F2 to
move among them.
</li>
<li>
Class documentation goes in the @classdesc descriptor for the class' constructor.
</li>
</ul>
</body>
</html>