| blob | 1d45f0a73dc9bab189958d08a331b4666529f64e |
5 <head>
8 <title>
9 Scintilla and SciTE Code Style Preferences
10 </title>
11 <style>
12 .S0 {
13 color: #808080;
14 }
15 .S1 {
16 font-family: Comic Sans MS;
17 color: #007F00;
18 font-size: 9pt;
19 }
20 .S2 {
21 font-family: Comic Sans MS;
22 color: #007F00;
23 font-size: 9pt;
24 }
25 .S3 {
26 font-family: Comic Sans MS;
27 color: #3F703F;
28 font-size: 9pt;
29 }
30 .S4 {
31 color: #007F7F;
32 }
33 .S5 {
34 font-weight: bold;
35 color: #00007F;
36 }
37 .S6 {
38 color: #7F007F;
39 }
40 .S7 {
41 color: #7F007F;
42 }
43 .S8 {
44 color: #804080;
45 }
46 .S9 {
47 color: #7F7F00;
48 }
49 .S10 {
50 font-weight: bold;
51 color: #000000;
52 }
53 .S12 {
54 font-family: Courier New;
55 color: #000000;
56 background: #E0C0E0;
57 font-size: 10pt;
58 }
59 .S13 {
60 font-family: Courier New;
61 color: #007F00;
62 background: #E0FFE0;
63 font-size: 10pt;
64 }
65 .S14 {
66 font-family: Courier New;
67 color: #3F7F3F;
68 background: #E0F0FF;
69 font-size: 10pt;
70 }
71 .S15 {
72 font-family: Comic Sans MS;
73 color: #3F703F;
74 font-size: 9pt;
75 }
76 SPAN {
77 font-family: Verdana;
78 font-size: 10pt;
79 }
80 </style>
81 </head>
84 <tr>
85 <td>
87 </td>
88 <td>
90 and SciTE</font></a>
91 </td>
92 </tr>
93 </table>
94 <h2>
95 Code Style
96 </h2>
97 <h3>
98 Introduction
99 </h3>
100 <p>
101 The source code of Scintilla and SciTE follow my preferences.
102 Some of these decisions are arbitrary and based on my sense of aesthetics
103 but its good to have all the code look the same even if its not exactly how
104 everyone would prefer.
105 </p>
106 <p>
107 Code that does not follow these conventions will be accepted, but will be modified
108 as time goes by to fit the conventions. Scintilla code follows the conventions more
109 closely than SciTE except for lexers which are relatively independent modules.
110 Lexers that are maintained by others are left as they are submitted except that
111 warnings will be fixed so the whole project can compile cleanly.
112 </p>
113 <p>
115 program with '-taOHUKk3 -M8' arguments formats code in much the right way although
116 there are a few bugs in AStyle.
117 </p>
118 <h3>
119 Language features
120 </h3>
121 <p>
122 Design goals for Scintilla and SciTE include portability to currently available C++
123 compilers on diverse platforms with high performance and low resource usage.
124 Scintilla has stricter portability requirements to SciTE as it may be ported to
125 low capability platforms.
126 </p>
127 <p>
128 To achieve portability, only a subset of C++ features are used.
129 Exceptions and templates may be used but, since Scintilla can be used from C as well as
130 C++, exceptions may not be thrown out of Scintilla and all exceptions should be caught
131 before returning from Scintilla.
132 Run-time type information adds to memory use so is turned off.
133 A 'Scintilla' name spaces is optionally used based on the SCI_NAMESPACE
134 definition. This helps with name clashes on OS X.
135 </p>
136 <p>
137 The goto statement is not used because of bad memories from my first job
138 maintaining FORTRAN programs. The union feature is not used as it can lead to
139 non-type-safe value access.
140 </p>
141 <h3>
142 Casting
143 </h3>
144 <p>
145 Do not use old C style casts like (char *)s. Instead use the most strict form of C++
147 where possible rather than reinterpret_cast. Because the code is compiled with
148 run-time type information turned off, dynamic_cast will not work.
149 </p>
150 <p>
151 The benefit to using the new style casts is that they explicitly detail what evil is
152 occurring and act as signals that something potentially unsafe is being done.
153 </p>
154 <p>
155 Code that treats const seriously is easier to reason about both for humans
156 and compilers, so use const parameters and avoid const_cast.
157 </p>
158 <h3>
159 Warnings
160 </h3>
161 <p>
162 To help ensure code is well written and portable, it is compiled with almost all
163 warnings turned on. This sometimes results in warnings about code that is
164 completely good (false positives) but changing the code to avoid the warnings
165 is generally fast and has little impact on readability.
166 </p>
167 <p>
168 Initialise all variables and minimise the scope of variables. If a variable is defined
169 just before its use then it can't be misused by code before that point.
170 Use loop declarations that are compatible with both the C++ standard and currently
171 available compilers.
172 </p>
173 <h3>
174 Allocation
175 </h3>
176 <p>
177 Memory exhaustion can occur in many Scintilla methods.
178 This should be checked for and handled but once it has happened, it is very difficult to do
179 anything as Scintilla's data structures may be in an inconsistent state.
180 Fixed length buffers are often used as these are simple and avoid the need to
181 worry about memory exhaustion but then require that buffer lengths are
182 respected.
183 </p>
184 <p>
185 The C++ new and delete operators are preferred over C's malloc and free
186 as new and delete are type safe.
187 </p>
188 <h3>
189 Bracketing
190 </h3>
191 <p>
192 Start brackets, '{', should be located on the line of the control structure they
193 start and end brackets, '}', should be at the indented start of a line. When there is
194 an else clause, this occurs on the same line as the '}'.
195 This format uses less lines than alternatives, allowing more code to be seen on screen.
196 Fully bracketed control
197 structures are preferred because this makes it more likely that modifications will
198 be correct and it allows Scintilla's folder to work. No braces on returned
199 expressions as return is a keyword, not a function call.
200 </p>
201 <SPAN class=S0></SPAN><SPAN class=S5>bool</SPAN><SPAN class=S0> </SPAN><SPAN class=S11>fn</SPAN><SPAN class=S10>(</SPAN><SPAN class=S5>int</SPAN><SPAN class=S0> </SPAN><SPAN class=S11>a</SPAN><SPAN class=S10>)</SPAN><SPAN class=S0> </SPAN><SPAN class=S10>{</SPAN><SPAN class=S0><BR>
202 </SPAN><SPAN class=S5>if</SPAN><SPAN class=S0> </SPAN><SPAN class=S10>(</SPAN><SPAN class=S11>a</SPAN><SPAN class=S10>)</SPAN><SPAN class=S0> </SPAN><SPAN class=S10>{</SPAN><SPAN class=S0><BR>
203 </SPAN><SPAN class=S11>s</SPAN><SPAN class=S10>();</SPAN><SPAN class=S0><BR>
204 </SPAN><SPAN class=S11>t</SPAN><SPAN class=S10>();</SPAN><SPAN class=S0><BR>
205 </SPAN><SPAN class=S10>}</SPAN><SPAN class=S0> </SPAN><SPAN class=S5>else</SPAN><SPAN class=S0> </SPAN><SPAN class=S10>{</SPAN><SPAN class=S0><BR>
206 </SPAN><SPAN class=S11>u</SPAN><SPAN class=S10>();</SPAN><SPAN class=S0><BR>
207 </SPAN><SPAN class=S10>}</SPAN><SPAN class=S0><BR>
208 </SPAN><SPAN class=S5>return</SPAN><SPAN class=S0> </SPAN><SPAN class=S10>!</SPAN><SPAN class=S11>a</SPAN><SPAN class=S10>;</SPAN><SPAN class=S0><BR>
210 </SPAN> <h3>
211 Spacing
212 </h3>
213 <p>
214 Spaces on both sides of '=' and comparison operators and no attempt to line up '='.
215 No space before or after '(', when used in calls, but a space after every ','.
216 No spaces between tokens in short expressions but may be present in
217 longer expressions. Space before '{'. No space before ';'.
218 No space after '*' when used to mean pointer and no space after '[' or ']'.
219 One space between keywords and '('.
220 </p>
221 <SPAN class=S0></SPAN><SPAN class=S5>void</SPAN><SPAN class=S0> </SPAN><SPAN class=S11>StoreConditionally</SPAN><SPAN class=S10>(</SPAN><SPAN class=S5>int</SPAN><SPAN class=S0> </SPAN><SPAN class=S11>c</SPAN><SPAN class=S10>,</SPAN><SPAN class=S0> </SPAN><SPAN class=S5>const</SPAN><SPAN class=S0> </SPAN><SPAN class=S5>char</SPAN><SPAN class=S0> </SPAN><SPAN class=S10>*</SPAN><SPAN class=S11>s</SPAN><SPAN class=S10>)</SPAN><SPAN class=S0> </SPAN><SPAN class=S10>{</SPAN><SPAN class=S0><BR>
222 </SPAN><SPAN class=S5>if</SPAN><SPAN class=S0> </SPAN><SPAN class=S10>(</SPAN><SPAN class=S11>c</SPAN><SPAN class=S0> </SPAN><SPAN class=S10>&&</SPAN><SPAN class=S0> </SPAN><SPAN class=S10>(</SPAN><SPAN class=S11>baseSegment</SPAN><SPAN class=S0> </SPAN><SPAN class=S10>==</SPAN><SPAN class=S0> </SPAN><SPAN class=S11>trustSegment</SPAN><SPAN class=S10>[</SPAN><SPAN class=S6>"html"</SPAN><SPAN class=S10>]))</SPAN><SPAN class=S0> </SPAN><SPAN class=S10>{</SPAN><SPAN class=S0><BR>
223 </SPAN><SPAN class=S11>baseSegment</SPAN><SPAN class=S0> </SPAN><SPAN class=S10>=</SPAN><SPAN class=S0> </SPAN><SPAN class=S11>s</SPAN><SPAN class=S10>+</SPAN><SPAN class=S4>1</SPAN><SPAN class=S10>;</SPAN><SPAN class=S0><BR>
224 </SPAN><SPAN class=S11>Store</SPAN><SPAN class=S10>(</SPAN><SPAN class=S11>s</SPAN><SPAN class=S10>,</SPAN><SPAN class=S0> </SPAN><SPAN class=S11>baseSegment</SPAN><SPAN class=S10>,</SPAN><SPAN class=S0> </SPAN><SPAN class=S6>"html"</SPAN><SPAN class=S10>);</SPAN><SPAN class=S0><BR>
225 </SPAN><SPAN class=S10>}</SPAN><SPAN class=S0><BR>
227 <h3>
228 Names
229 </h3>
230 <p>
231 Identifiers use mixed case and no underscores.
232 Class, function and method names start with an uppercase letter and use
233 further upper case letters to distinguish words. Variables start with a lower
234 case letter and use upper case letters to distinguish words.
235 Loop counters and similar variables can have simple names like 'i'.
236 Function calls should be differentiated from method calls with an initial '::'
237 global scope modifier.
238 </p>
239 <SPAN class=S0></SPAN><SPAN class=S5>class</SPAN><SPAN class=S0> </SPAN><SPAN class=S11>StorageZone</SPAN><SPAN class=S0> </SPAN><SPAN class=S10>{</SPAN><SPAN class=S0><BR>
241 </SPAN><SPAN class=S5>void</SPAN><SPAN class=S0> </SPAN><SPAN class=S11>Store</SPAN><SPAN class=S10>(</SPAN><SPAN class=S5>const</SPAN><SPAN class=S0> </SPAN><SPAN class=S5>char</SPAN><SPAN class=S0> </SPAN><SPAN class=S10>*</SPAN><SPAN class=S11>s</SPAN><SPAN class=S10>)</SPAN><SPAN class=S0> </SPAN><SPAN class=S10>{</SPAN><SPAN class=S0><BR>
242 </SPAN><SPAN class=S11>Media</SPAN><SPAN class=S0> </SPAN><SPAN class=S10>*</SPAN><SPAN class=S11>mediaStore</SPAN><SPAN class=S0> </SPAN><SPAN class=S10>=</SPAN><SPAN class=S0> </SPAN><SPAN class=S10>::</SPAN><SPAN class=S11>GetBaseMedia</SPAN><SPAN class=S10>(</SPAN><SPAN class=S11>zoneDefault</SPAN><SPAN class=S10>);</SPAN><SPAN class=S0><BR>
243 </SPAN><SPAN class=S5>for</SPAN><SPAN class=S0> </SPAN><SPAN class=S10>(</SPAN><SPAN class=S5>int</SPAN><SPAN class=S0> </SPAN><SPAN class=S11>i</SPAN><SPAN class=S10>=</SPAN><SPAN class=S11>mediaStore</SPAN><SPAN class=S10>-></SPAN><SPAN class=S11>cursor</SPAN><SPAN class=S10>;</SPAN><SPAN class=S0> </SPAN><SPAN class=S11>mediaStore</SPAN><SPAN class=S10>[</SPAN><SPAN class=S11>i</SPAN><SPAN class=S10>],</SPAN><SPAN class=S0> </SPAN><SPAN class=S11>i</SPAN><SPAN class=S10>++)</SPAN><SPAN class=S0> </SPAN><SPAN class=S10>{</SPAN><SPAN class=S0><BR>
244 </SPAN><SPAN class=S11>mediaStore</SPAN><SPAN class=S10>-></SPAN><SPAN class=S11>Persist</SPAN><SPAN class=S10>(</SPAN><SPAN class=S11>s</SPAN><SPAN class=S10>[</SPAN><SPAN class=S11>i</SPAN><SPAN class=S10>]);</SPAN><SPAN class=S0><BR>
245 </SPAN><SPAN class=S10>}</SPAN><SPAN class=S0><BR>
246 </SPAN><SPAN class=S10>}</SPAN><SPAN class=S0><BR>
248 <h3>
249 Submitting a lexer
250 </h3>
252 <p>Add a public feature request to the <a href="https://sourceforge.net/tracker/?group_id=2439&atid=352439">Feature Request Tracker</a>.</p>
253 <p>Send all the modified and new files as full text (not patches) in an archive (.zip or .tgz).</p>
255 <p>Ensure there are no warnings under the compiler you use. Warnings from other compilers
256 will be noted on the feature request.</p>
258 </body>
259 </html>