summaryrefslogtreecommitdiffstats
path: root/doc/other/SciCoding.html
blob: df0eb9004a72de6f656c9c5343ae8e5f220fac33 (plain)
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
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta name="generator" content="SciTE" />
    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
    <title>
      Scintilla and SciTE Code Style Preferences
    </title>
	<style>
	.S0 {
		color: #808080;
	}
	.S1 {
		font-family: Comic Sans MS;
		color: #007F00;
		font-size: 9pt;
	}
	.S2 {
		font-family: Comic Sans MS;
		color: #007F00;
		font-size: 9pt;
	}
	.S3 {
		font-family: Comic Sans MS;
		color: #3F703F;
		font-size: 9pt;
	}
	.S4 {
		color: #007F7F;
	}
	.S5 {
		font-weight: bold;
		color: #00007F;
	}
	.S6 {
		color: #7F007F;
	}
	.S7 {
		color: #7F007F;
	}
	.S8 {
		color: #804080;
	}
	.S9 {
		color: #7F7F00;
	}
	.S10 {
		font-weight: bold;
		color: #000000;
	}
	.S12 {
		font-family: Courier New;
		color: #000000;
		background: #E0C0E0;
		font-size: 10pt;
	}
	.S13 {
		font-family: Courier New;
		color: #007F00;
		background: #E0FFE0;
		font-size: 10pt;
	}
	.S14 {
		font-family: Courier New;
		color: #3F7F3F;
		background: #E0F0FF;
		font-size: 10pt;
	}
	.S15 {
		font-family: Comic Sans MS;
		color: #3F703F;
		font-size: 9pt;
	}
	SPAN {
		font-family: Verdana;
		font-size: 10pt;
	}
	</style>
  </head>
  <body bgcolor="#FFFFFF" text="#000000">
    <table bgcolor="#000000" width="100%" cellspacing="0" cellpadding="0" border="0">
      <tr>
        <td>
          <img src="SciTEIco.png" border="3" height="64" width="64" alt="Scintilla icon" />
        </td>
        <td>
          <a href="index.html" style="color:white;text-decoration:none"><font size="5">Scintilla
          and SciTE</font></a>
        </td>
      </tr>
    </table>
    <h2>
       Code Style
    </h2>
    <h3>
       Introduction
    </h3>
	<p>
	The source code of Scintilla and SciTE follow my preferences. 
	Some of these decisions are arbitrary and based on my sense of aesthetics
	but its good to have all the code look the same even if its not exactly how
	everyone would prefer.
	</p>
	<p>
	Code that does not follow these conventions will be accepted, but will be modified
	as time goes by to fit the conventions. Scintilla code follows the conventions more 
	closely than SciTE except for lexers which are relatively independent modules. 
	Lexers that are maintained by others are left as they are submitted except that
	warnings will be fixed so the whole project can compile cleanly.
	</p>
	<p>
	The <a href="http://astyle.sourceforge.net/">AStyle</a> formatting 
	program with a '-tapO' argument formats code in much the right way although 
	there are a few bugs in AStyle. The scite/scripts/Fixer.py script will run AStyle
	over a C++ source file and fix up some of those bugs.
	</p>
    <h3>
       Language features
    </h3>
	<p>
	Design goals for Scintilla and SciTE include portability to currently available C++ 
	compilers on diverse platforms with high performance and low resource usage.
	Scintilla has stricter portability requirements to SciTE as it may be ported to 
	low capability platforms such as Windows CE or PalmOS but it is less likely
	SciTE will be.
	</p>
	<p>
	To achieve portability, only a subset of C++ features are used. Exceptions are 
	not available on some platforms such as Windows CE so exceptions are not used
	and thus the standard C++ library can not be used. 
	Template support differs between compilers so is not used in Scintilla but there
	are some simple uses in SciTE.
	Run-time type information adds to memory use so is turned off. 
	Name spaces are not used.
	</p>
	<p>
	The goto statement is not used because of bad memories from my first job 
	maintaining FORTRAN programs. The union feature is not used as it can lead to 
	non-type-safe value access.
	</p>
    <h3>
       Casting
    </h3>
	<p>
	Do not use old C style casts like (char *)s. Instead use the most strict form of C++ 
	cast possible like const_cast&lt;char *&gt;(s). Use static_cast and const_cast 
	where possible rather than reinterpret_cast. Because the code is compiled with 
	run-time type information turned off, dynamic_cast will not work.
	</p>
	<p>
	The benefit to using the new style casts is that they explicitly detail what evil is
	occurring and act as signals that something potentially unsafe is being done.
	</p>
	<p>
	Code that treats const seriously is easier to reason about both for humans
	and compilers, so use const parameters and avoid const_cast.
	</p>
    <h3>
       Warnings
    </h3>
	<p>
	To help ensure code is well written and portable, it is compiled with almost all
	warnings turned on. This sometimes results in warnings about code that is 
	completely good (false positives) but changing the code to avoid the warnings 
	is generally fast and has little impact on readability. 
	</p>
	<p>
	Initialise all variables and minimise the scope of variables. If a variable is defined
	just before its use then it can't be misused by code before that point.
	Use loop declarations that are compatible with both the C++ standard and currently 
	available compilers. 
	</p>
    <h3>
       Allocation
    </h3>
	<p>
	As exceptions are not used, memory exhaustion can occur. 
	This should be checked for and handled but there is quite a lot of Scintilla and
	SciTE code that doesn't yet. 
	Fixed length buffers are often used as these are simple and avoid the need to 
	worry about memory exhaustion but then require that buffer lengths are 
	respected. 
	</p>
	<p>
	The C++ new and delete operators are preferred over C's malloc and free
	as new and delete are type safe.
	</p>
    <h3>
       Bracketing
    </h3>
	<p>
	Start brackets, '{', should be located on the line of the control structure they
	start and end brackets, '}', should be at the indented start of a line. When there is
	an else clause, this occurs on the same line as the '}'. 
	This format uses less lines than alternatives, allowing more code to be seen on screen.
	Fully bracketed control 
	structures are preferred because this makes it more likely that modifications will 
	be correct and it allows Scintilla's folder to work. No braces on returned 
	expressions as return is a keyword, not a function call.
	</p>
<SPAN class=S0></SPAN><SPAN class=S5>bool</SPAN><SPAN class=S0>&nbsp;</SPAN><SPAN class=S11>fn</SPAN><SPAN class=S10>(</SPAN><SPAN class=S5>int</SPAN><SPAN class=S0>&nbsp;</SPAN><SPAN class=S11>a</SPAN><SPAN class=S10>)</SPAN><SPAN class=S0>&nbsp;</SPAN><SPAN class=S10>{</SPAN><SPAN class=S0><BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</SPAN><SPAN class=S5>if</SPAN><SPAN class=S0>&nbsp;</SPAN><SPAN class=S10>(</SPAN><SPAN class=S11>a</SPAN><SPAN class=S10>)</SPAN><SPAN class=S0>&nbsp;</SPAN><SPAN class=S10>{</SPAN><SPAN class=S0><BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</SPAN><SPAN class=S11>s</SPAN><SPAN class=S10>();</SPAN><SPAN class=S0><BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</SPAN><SPAN class=S11>t</SPAN><SPAN class=S10>();</SPAN><SPAN class=S0><BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</SPAN><SPAN class=S10>}</SPAN><SPAN class=S0>&nbsp;</SPAN><SPAN class=S5>else</SPAN><SPAN class=S0>&nbsp;</SPAN><SPAN class=S10>{</SPAN><SPAN class=S0><BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</SPAN><SPAN class=S11>u</SPAN><SPAN class=S10>();</SPAN><SPAN class=S0><BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</SPAN><SPAN class=S10>}</SPAN><SPAN class=S0><BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</SPAN><SPAN class=S5>return</SPAN><SPAN class=S0>&nbsp;</SPAN><SPAN class=S10>!</SPAN><SPAN class=S11>a</SPAN><SPAN class=S10>;</SPAN><SPAN class=S0><BR>
</SPAN><SPAN class=S10>}</SPAN><SPAN class=S0><BR>
</SPAN>    <h3>
       Spacing
    </h3>
	<p>
	Spaces on both sides of '=' and comparison operators and no attempt to line up '='. 
	No space before or after '(', when used in calls, but a space after every ','.
	No spaces between tokens in short expressions but may be present in 
	longer expressions. Space before '{'. No space before ';'. 
	No space after '*' when used to mean pointer and no space after '[' or ']'.
	One space between keywords and '('.
	</p>
<SPAN class=S0></SPAN><SPAN class=S5>void</SPAN><SPAN class=S0>&nbsp;</SPAN><SPAN class=S11>StoreConditionally</SPAN><SPAN class=S10>(</SPAN><SPAN class=S5>int</SPAN><SPAN class=S0>&nbsp;</SPAN><SPAN class=S11>c</SPAN><SPAN class=S10>,</SPAN><SPAN class=S0>&nbsp;</SPAN><SPAN class=S5>const</SPAN><SPAN class=S0>&nbsp;</SPAN><SPAN class=S5>char</SPAN><SPAN class=S0>&nbsp;</SPAN><SPAN class=S10>*</SPAN><SPAN class=S11>s</SPAN><SPAN class=S10>)</SPAN><SPAN class=S0>&nbsp;</SPAN><SPAN class=S10>{</SPAN><SPAN class=S0><BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</SPAN><SPAN class=S5>if</SPAN><SPAN class=S0>&nbsp;</SPAN><SPAN class=S10>(</SPAN><SPAN class=S11>c</SPAN><SPAN class=S0>&nbsp;</SPAN><SPAN class=S10>&amp;&amp;</SPAN><SPAN class=S0>&nbsp;</SPAN><SPAN class=S10>(</SPAN><SPAN class=S11>baseSegment</SPAN><SPAN class=S0>&nbsp;</SPAN><SPAN class=S10>==</SPAN><SPAN class=S0>&nbsp;</SPAN><SPAN class=S11>trustSegment</SPAN><SPAN class=S10>[</SPAN><SPAN class=S6>"html"</SPAN><SPAN class=S10>]))</SPAN><SPAN class=S0>&nbsp;</SPAN><SPAN class=S10>{</SPAN><SPAN class=S0><BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</SPAN><SPAN class=S11>baseSegment</SPAN><SPAN class=S0>&nbsp;</SPAN><SPAN class=S10>=</SPAN><SPAN class=S0>&nbsp;</SPAN><SPAN class=S11>s</SPAN><SPAN class=S10>+</SPAN><SPAN class=S4>1</SPAN><SPAN class=S10>;</SPAN><SPAN class=S0><BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</SPAN><SPAN class=S11>Store</SPAN><SPAN class=S10>(</SPAN><SPAN class=S11>s</SPAN><SPAN class=S10>,</SPAN><SPAN class=S0>&nbsp;</SPAN><SPAN class=S11>baseSegment</SPAN><SPAN class=S10>,</SPAN><SPAN class=S0>&nbsp;</SPAN><SPAN class=S6>"html"</SPAN><SPAN class=S10>);</SPAN><SPAN class=S0><BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</SPAN><SPAN class=S10>}</SPAN><SPAN class=S0><BR>
</SPAN><SPAN class=S10>}</SPAN>
    <h3>
       Names
    </h3>
	<p>
	Identifiers use mixed case and no underscores.
	Class, function and method names start with an uppercase letter and use
	further upper case letters to distinguish words. Variables start with a lower 
	case letter and use upper case letters to distinguish words. 
	Loop counters and similar variables can have simple names like 'i'.
	Function calls should be differentiated from method calls with an initial '::' 
	global scope modifier.
	</p>
<SPAN class=S0></SPAN><SPAN class=S5>class</SPAN><SPAN class=S0>&nbsp;</SPAN><SPAN class=S11>StorageZone</SPAN><SPAN class=S0>&nbsp;</SPAN><SPAN class=S10>{</SPAN><SPAN class=S0><BR>
</SPAN><SPAN class=S5>public</SPAN><SPAN class=S10>:</SPAN><SPAN class=S0><BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</SPAN><SPAN class=S5>void</SPAN><SPAN class=S0>&nbsp;</SPAN><SPAN class=S11>Store</SPAN><SPAN class=S10>(</SPAN><SPAN class=S5>const</SPAN><SPAN class=S0>&nbsp;</SPAN><SPAN class=S5>char</SPAN><SPAN class=S0>&nbsp;</SPAN><SPAN class=S10>*</SPAN><SPAN class=S11>s</SPAN><SPAN class=S10>)</SPAN><SPAN class=S0>&nbsp;</SPAN><SPAN class=S10>{</SPAN><SPAN class=S0><BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</SPAN><SPAN class=S11>Media</SPAN><SPAN class=S0>&nbsp;</SPAN><SPAN class=S10>*</SPAN><SPAN class=S11>mediaStore</SPAN><SPAN class=S0>&nbsp;</SPAN><SPAN class=S10>=</SPAN><SPAN class=S0>&nbsp;</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>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</SPAN><SPAN class=S5>for</SPAN><SPAN class=S0>&nbsp;</SPAN><SPAN class=S10>(</SPAN><SPAN class=S5>int</SPAN><SPAN class=S0>&nbsp;</SPAN><SPAN class=S11>i</SPAN><SPAN class=S10>=</SPAN><SPAN class=S11>mediaStore</SPAN><SPAN class=S10>-&gt;</SPAN><SPAN class=S11>cursor</SPAN><SPAN class=S10>;</SPAN><SPAN class=S0>&nbsp;</SPAN><SPAN class=S11>mediaStore</SPAN><SPAN class=S10>[</SPAN><SPAN class=S11>i</SPAN><SPAN class=S10>],</SPAN><SPAN class=S0>&nbsp;</SPAN><SPAN class=S11>i</SPAN><SPAN class=S10>++)</SPAN><SPAN class=S0>&nbsp;</SPAN><SPAN class=S10>{</SPAN><SPAN class=S0><BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</SPAN><SPAN class=S11>mediaStore</SPAN><SPAN class=S10>-&gt;</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>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</SPAN><SPAN class=S10>}</SPAN><SPAN class=S0><BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</SPAN><SPAN class=S10>}</SPAN><SPAN class=S0><BR>
</SPAN><SPAN class=S10>};</SPAN>
  </body>
</html>