Scintilla and SciTE Code Style Preferences

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 '-taOHUKk3 -M8' arguments formats code in much the right way although there are a few bugs in AStyle.

Language features

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.

To achieve portability, only a subset of C++ features are used. Exceptions and templates may be used but, since Scintilla can be used from C as well as C++, exceptions may not be thrown out of Scintilla and all exceptions should be caught before returning from Scintilla. Run-time type information adds to memory use so is turned off. A 'Scintilla' name spaces is optionally used based on the SCI_NAMESPACE definition. This helps with name clashes on OS X.

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

Memory exhaustion can occur in many Scintilla methods. This should be checked for and handled but once it has happened, it is very difficult to do anything as Scintilla's data structures may be in an inconsistent state. 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]);
                }
        }
};

Submitting a lexer

Add a public feature request to the Feature Request Tracker.

Send all the modified and new files as full text (not patches) in an archive (.zip or .tgz).

Define all of the lexical states in a modified Scintilla.iface.

Ensure there are no warnings under the compiler you use. Warnings from other compilers will be noted on the feature request.

sc.ch is an int: do not pass this around as a char.