Home/Delphi Worlds Coding Standards
Delphi Worlds Coding Standards 2017-05-12T09:20:30+00:00

Delphi Worlds Coding Standards

Prologue

Intention

This is a set of coding standards for Delphi only. Not every coding situation is catered for in this document. Where you are unsure, please consult a senior developer and/or the Development Team Leader. This may lead to the document being further enhanced.

Examples

There are already many examples of code following these coding standards in the existing Kastri library, so please use those as a reference.

Breaches of the standards

If you notice any code that does not adhere to the standards, please notify the Development Team Leader.

Code organisation

This document outlines standards for what is contained in the source files themselves. For overall organisation of code within projects, please refer to the Delphi Worlds Application Construction document.

Back To Top

Naming

Note: Where naming rules are used, the case of the naming must match as per examples given

Namespacing

Unit files are divided into logical namespaces. Framework code (shared amongst projects) are to use the DW prefix.

Framework units should be named using the Embarcadero naming style.

For platform api units:

<prefix>.<platform>api.<functionality>.pas, e.g.:

DW.iOSapi.Photos.pas

For platform agnostic units: <prefix>.<functionality>.pas, e.g.:

DW.SuperWidget.pas

For platform specific units that consume a platform api: <prefix>.<functionality>.<platform>.pas, e.g.:

DW.SuperWidget.iOS.pas

Project specific units are to use the codename for that project: <projectprefix>.<unitname>.pas, e.g.:

MM.Types.pas

Unit naming

Form and frame units shall use the suffix: .View, e.g:

SDX.Main.View.pas

<needs more content here>

Component Naming

<content here re form, frame and datamodule naming>

Components shall have a meaningful name, and be suffixed with the component type, minus the T and vendor prefix, e.g: a TLayout might be named UpperLayout, a TEdit might be named UsernameEdit, a TFDTable might be named ListsTable.

Type naming

All distinct types shall be named starting with a capital T

Event handler method naming

Event handler methods shall be named logically, pertaining to the event they are handling (with the word “On” removed, if it has one), and be suffixed with the word: Handler, e.g. if a handler is assigned in code to the OnClick event of a button called CancelButton, the handler should be named: CancelButtonClickHandler

Variable naming

Field variables (i.e. in classes) are to be prefixed with a capital F

Local variables are to be prefixed with a capital L, with the exception of integer loop variables, which should be named I for the first, J for the second, and so on.

Back To Top

Declarations

Types

Types shall be declared on a line immediately following the previous line, except in the case of classes and records, which shall be separated by one blank line

Classes

Visibility specifiers shall be on a new line, in order of the visibility, i.e. the order is:

• strict private

• private

• strict protected

• protected

• public

• published

Field variables for each visibility shall appear first, in alphabetical order, with the exception of event reference variables, which follow the other field variables, and the event reference variables shall also be in alphabetical order within themselves.

Methods shall follow the field variables, also in alphabetical order.

Exceptions:

Constructors and destructors – these shall appear first in any visibility section, in this order:

• class constructors

• class destructors

• constructors

• destructors

Methods that are implementation of interfaces: these shall always appear in their own protected section, preceded by a braced comment that indicates the interface being implemented, e.g:

Properties shall follow the methods, also in alphabetical order, with the exception of event properties, which shall follow the other properties, however the event properties shall also be in alphabetical order

The only exception to the above rules is for IDE generated classes: forms, frames and datamodules, where the auto-generated published component and event handler references appear first.

Interfaces

Interfaces shall be declared similarly to classes, with method declarations first, in alphabetical order, then properties, also in alphabetical order

Back To Top

Code Structures

with

Under no circumstances is “with” to be used. No discussions will be entered into.

Uses clauses

Units that are used by another, should appear in the section of lowest scope, i.e. if a unit imports symbols from another unit that are required only the implementation section, the used unit shall appear in the implementation section of the unit using it. This is to avoid creating greater dependency than is required, and avoids having to resolve circular references.

Finally Blocks

Code inside a finally block is to execute resource deallocation only, e.g. calling Free, DisposeOf, releasing of handles, etc.

Checking For Assignment

Use the Assigned method for event handlers only. All other checks for assignment shall be compared against nil.

Global Variables

Global variables are to be avoided, unless there is a very good reason to use them. They must be approved by the Development Team Leader. Globals created by the IDE such as frmMain etc are to be ignored. Instead, consider the scope of use, and perhaps access via a class variable (example)

Back To Top

Formatting

Margin

The margin is set at 150 characters. Whole expressions and individual parameter declarations including their type, going beyond the margin, shall be moved to the next line, and be indented by 2 spaces.  Unit names in unit clauses going beyond the margin shall also be moved to the next line, at the same indentation as the line before.

Case

Keywords (represented by bold in the Delphi IDE) are to be all lowercase

Constants are to start with a lowercase c.

All other identifiers are to start with a capital

Indentation

• All declaration section headers(uses, type, const, procedure etc) are to start in the first column

• All declarations within a declaration section are to be indented by 2 spaces

• Code blocks (eg inside a try..finally, within a begin..end, code that is executed by an if or for statement) are to be indented 2 spaces

Spacing

Blank lines:

• Always consider as being before a declaration (aside from unit name at beginning)

• No blank lines within a declaration (i.e. record, class, method)

• No multiple blank lines

Spaces within lines:

• Only one space should separate identifiers, operators etc, i.e. no aligning of declarations using multiple spaces

Operators must be separated by a space, eg:

LHeight := (Screen.Height / 2) + (Height / 2);

• No spaces before or after parentheses, except for before a constant array declaration

Statements

All statements, where possible, shall be terminated by a semicolon, even where the compiler will allow no semicolon.

Code Blocks

The begin in a begin..end code block is to start on a new line.

Structured Statements

if/while statements:

Where the conditional code of an if/while statement spans more than one line, even if it is only one statement, the conditional code is to be enclosed in a begin..end block. The begin is to be aligned to the if (example). An if following the else in another if statement is to appear immediately after the else. e.g.

repeat..until statements:

The code inside a repeat..until statement is to be indented 2 spaces

case statements:

• Each case condition is to start on a new line, and be indented 2 spaces in relation to case

• Each code block for the case condition is to be enclosed in a begin..end block, which is aligned to the condition, e.g:

Back To Top

Documentation and comments

XML Documentation

Where the intention of a method may be unclear, XML Documentation may be used to clarify the intention. The documentation must immediately precede the method declaration, and must contain at least the summary tag.

Comments

Comments must appear on their own lines (i.e. not on the same line as code), and must be used for clarifying what the code is intended for. Comments must use the double slash style, i.e. //

Code must not be commented out completely unless it is part of work in progress, i.e. any code intended for promotion that is commented out must be removed, because the code would already exist in the source control history.

Back To Top

Show Buttons
Hide Buttons