User:Kai Burghardt/Style guide

naming scheme

no Hungarian notation

Hungarian notation is the naming style, where identifier start with letters associated with certain type categories. Always give meaningful names.

camel-case identifiers

Pascal is case-insensitive.

Identifiers do not contain underscores.

Do not write snake-case identifiers, unless they originate from foreign libraries (probably written in C)

names optionally follow a hierarchy

E.g. there are the range types fooDomain and fooCodomain, both starting with foo. Or, in another example, there are staffMember = record … end; and staffMemberReference = ^staffMember;, both starting with staffMember. So related identifiers could appear next to each other in an alphabetical listing of them. But do not enforce this idea. Note: Unit scopes and namespaces automatically form a hierarchy. Ensure the fully qualified identifier does not contain any redundancies.

Do not abbreviate within identifiers. At no point, ever.

Being lazy and abbreviating (or worse), does not improve readability. Although it is tedious to spell out everything, it will serve you well when revisiting code that hasn't been seen for months. Don't save money in the wrong place. Properly named identifiers are a case in point.

plural nouns refer to collections, singular nouns to individual objects

e.g. there is an enumeration type mode, then the data type modes – plural – will refer to a set of mode (or other sort of collection)

LOC

Indent with tabulators.

They take one byte, versus two or more bytes for spaces.

Always write begin and end where it is allowed.

This will minimize risks of erroneously thinking something belongs to a certain language construct.

Even repeat … until have their own begin … end even though it is redundant.

Unary operators are not separated by a space from their operand, unless it is a word.

Otherwise one could write 40 - - 2 which just looks ridiculous.

Binary operators are surrounded by a single space on each side.

Otherwise one could write 40--2. I don't like that. Write 40 - -2 and we're friends.

An opening parenthesis starting the parameter list always follows directly the identifier.

Do not write writeLn (42). The parameters “belong” to the identifier, thus ought to be right next to them. Write writeLn(42) with no blank inbetween and we're good.

design

use the strong typing system to your advantage

Consider the following “wrong” piece of code (on a 64-bit platform):

function foo(const x: qWord): qWord;
begin
	foo := x + 7;
end;

While you don't necessarily use range and overflow checks in a production program, Pascal allows you to thwart many errors already at compile-time. In general, define domains and co-domains of routines in a manner, where they are actually defined. That means for the example above

type
	fooDomain = 0..high(qWord)-7;
	fooCodomain = 7..high(qWord);
function foo(const x: fooDomain): fooCodomain;
begin
	foo := x + 7;
end;

Of course this is a trivial example, but consequently employing this technique makes it possible to spot errors via simple range checks. (see also tutorial: defensive programming techniques)

see also

• Do's and Don'ts
• Coding style, design guidelines, Nomenclature