+ Scintilla and SciTE Code Style Preferences +

From d6e1d0e0d448fadbb61f4533edbee88376cf7682 Mon Sep 17 00:00:00 2001 From: nyamatongwe Date: Mon, 16 Apr 2001 08:46:43 +0000 Subject: Initial version. --- doc/SciCoding.html | 251 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 251 insertions(+) create mode 100644 doc/SciCoding.html (limited to 'doc/SciCoding.html') diff --git a/doc/SciCoding.html b/doc/SciCoding.html new file mode 100644 index 000000000..46862f9e5 --- /dev/null +++ b/doc/SciCoding.html @@ -0,0 +1,251 @@ + + + + + + + + Scintilla and SciTE Code Style Preferences + + + + + + + + + +

+ +	+ Scintilla + and SciTE +

+ Code Style +

+ Introduction +

+ 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. +

+ 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. +

+ The AStyle 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. +

+ Language features +

+ Design goals for Scintilla and SciTE include portablity 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. +

+ 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. +

+ 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. +

+ Casting +

+ 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. +

+ 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. +

+ Code that treats const seriously is easier to reason about both for humans + and compilers, so use const parameters and avoid const_cast. +

+ Warnings +

+ 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. +

+ 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. +

+ Allocation +

+ 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. +

+ The C++ new and delete operators are preferred over C's malloc and free + as new and delete are type safe. +

+ Bracketing +

+ 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. +

+bool fn(int a) {
+        if (a) {
+                s();
+                t();
+        } else {
+                u();
+        }
+        return !a;
+}
+

+ Spacing +

+ 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 '('. +

+void StoreConditionally(int c, const char *s) {
+        if (c && (baseSegment == trustSegment["html"])) {
+                baseSegment = s+1;
+                Store(s, baseSegment, "html");
+        }
+} +

+ Names +

+ 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. +

+class StorageZone {
+public:
+        void Store(const char *s) {
+                Media *mediaStore = ::GetBaseMedia(zoneDefault);
+                for (int i=mediaStore->cursor; mediaStore[i], i++) {
+                        mediaStore->Persist(s[i]);
+                }
+        }
+}; + + -- cgit v1.2.3