You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
tqscintilla/doc/Scintilla/SciCoding.html

252 lines
13 KiB

<?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>