diff options
Diffstat (limited to 'doc/other/SciCoding.html')
| -rw-r--r-- | doc/other/SciCoding.html | 251 |
1 files changed, 251 insertions, 0 deletions
diff --git a/doc/other/SciCoding.html b/doc/other/SciCoding.html new file mode 100644 index 0000000..df0eb90 --- /dev/null +++ b/doc/other/SciCoding.html @@ -0,0 +1,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<char *>(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> </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> + </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> + </SPAN><SPAN class=S11>s</SPAN><SPAN class=S10>();</SPAN><SPAN class=S0><BR> + </SPAN><SPAN class=S11>t</SPAN><SPAN class=S10>();</SPAN><SPAN class=S0><BR> + </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> + </SPAN><SPAN class=S11>u</SPAN><SPAN class=S10>();</SPAN><SPAN class=S0><BR> + </SPAN><SPAN class=S10>}</SPAN><SPAN class=S0><BR> + </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> +</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> </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> + </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> + </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> + </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> + </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> </SPAN><SPAN class=S11>StorageZone</SPAN><SPAN class=S0> </SPAN><SPAN class=S10>{</SPAN><SPAN class=S0><BR> +</SPAN><SPAN class=S5>public</SPAN><SPAN class=S10>:</SPAN><SPAN class=S0><BR> + </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> + </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> + </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> + </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> + </SPAN><SPAN class=S10>}</SPAN><SPAN class=S0><BR> + </SPAN><SPAN class=S10>}</SPAN><SPAN class=S0><BR> +</SPAN><SPAN class=S10>};</SPAN> + </body> +</html> |