Fpsonar declarations

← Back to fpsonar

Twenty-three rules about how you declare things: one per line or grouped, sections merged or separate, types spelled out or inferred. Most are style, all are on by default**, and the last seven are configurable ban-lists rather than fixed rules.**

The house style these encode is "one declaration per line, with its type written out". The reason is diff-friendliness: a change to one variable then touches one line, and a reviewer sees exactly what changed.

One thing per declaration

edit

DeclareVariablesIndividually

edit

minor · on by default

Each variable gets its own declaration. Beyond diffs, this avoids the trap that var A, B: Integer looks like it might mean different types for each.

fpsonar complains about this

var
  Total, Count: Integer;

fpsonar accepts this

var
  Total: Integer;
  Count: Integer;

DeclareFieldsIndividually

edit

minor · on by default

The same for fields of a class or record.

fpsonar complains about this

type
  TPoint3D = record
    X, Y, Z: Double;
  end;

fpsonar accepts this

type
  TPoint3D = record
    X: Double;
    Y: Double;
    Z: Double;
  end;

DeclareParametersIndividually

edit

minor · on by default

Grouped parameters are the riskiest of the three, because const and var apply to the whole group: in procedure P(const A, B: string) both are const, which is usually intended — but in procedure P(A: Integer; var B, C: Integer) it is easy to lose track of which are output parameters.

fpsonar complains about this

procedure Move(X, Y: Integer);

fpsonar accepts this

procedure Move(X: Integer; Y: Integer);

Sections

edit

CombineVarSections

edit

minor · on by default

Two var sections in a row are one section. Splitting them suggests a distinction that does not exist.

fpsonar complains about this

var
  Total: Integer;
var
  Count: Integer;

fpsonar accepts this

var
  Total: Integer;
  Count: Integer;

CombineConstSections

edit

minor · on by default

The same for consecutive const sections.

fpsonar complains about this

const
  MaxRetries = 3;
const
  Timeout = 30;

fpsonar accepts this

const
  MaxRetries = 3;
  Timeout = 30;

CombineTypeSections

edit

minor · on by default

And for consecutive type sections. Note that in Pascal, types in one section can reference each other freely, which is often why a second section was unnecessary.

fpsonar complains about this

type
  TRow = record end;
type
  TTable = record end;

fpsonar accepts this

type
  TRow = record end;
  TTable = record end;

CombineVisibilitySections

edit

minor · on by default

Two private sections in one class should be one. Scattered sections of the same visibility make it hard to see the whole private surface.

fpsonar complains about this

type
  TReport = class
  private
    FLines: TStringList;
  public
    procedure Build;
  private
    FCount: Integer;
  end;

fpsonar accepts this

type
  TReport = class
  private
    FLines: TStringList;
    FCount: Integer;
  public
    procedure Build;
  end;

RemoveEmptyVisibilitySection

edit

minor · on by default

A visibility keyword with nothing after it. Usually left behind when its members moved.

fpsonar complains about this

type
  TReport = class
  private
  public
    procedure Build;
  end;

fpsonar accepts this

type
  TReport = class
  public
    procedure Build;
  end;

RemoveEmptyFieldSection

edit

minor · on by default

The same for an empty field section inside a record or class.

fpsonar complains about this

type
  TRow = record
  private
  public
    Name: string;
  end;

fpsonar accepts this

type
  TRow = record
  public
    Name: string;
  end;

Types written out

edit

InlineVarNoTypeInference

edit

minor · on by default

{$modeswitch inlinevars} lets you declare a variable where you first use it, and optionally let its type be inferred. Inference is the part this rule objects to: the reader then has to evaluate the expression to know the type, and a change to the expression silently changes the variable's type.

fpsonar complains about this

var Total := ComputeTotal;     // what type is Total?

fpsonar accepts this

var Total: Currency := ComputeTotal;

InlineConstNoTypeInference

edit

minor · on by default

The same for an inline constant.

fpsonar complains about this

const Limit := 100;

fpsonar accepts this

const Limit: Integer = 100;

InlineLoopVarNoTypeInference

edit

minor · on by default

And for a loop variable declared in the for statement. Here the inferred type also determines the loop's arithmetic, so it is worth stating.

fpsonar complains about this

for var I := 0 to Count - 1 do
  Process(I);

fpsonar accepts this

for var I: Integer := 0 to Count - 1 do
  Process(I);

FunctionReturnTypeRequired

edit

minor · on by default

A function must say what it returns. A function without a result type is either a procedure written wrongly or a syntax error waiting to happen.

fpsonar complains about this

function Total;

fpsonar accepts this

function Total: Integer;

NoObjectTypes

edit

major · on by default

object is the pre-Delphi record-with-methods type. It is still supported for backward compatibility but has awkward inheritance and lifetime rules, no interfaces, and no visibility beyond private/public. Use class for a heap object or record for a value.

fpsonar complains about this

type
  TPoint = object
    X, Y: Integer;
    procedure Move;
  end;

fpsonar accepts this

type
  TPoint = record
    X: Integer;
    Y: Integer;
    procedure Move;
  end;

Identifier constraints

edit

IdentifierTooShort

edit

minor · on by default · parameters minLength, plus an allow-list

Very short names carry no information. The rule allows the conventional single-letter names — i, j, k, x, y, z, n — because a loop counter called i is clearer than one called Index.

fpsonar complains about this

var
  c: TCustomer;               // c means nothing

fpsonar accepts this

var
  Customer: TCustomer;

DisallowedIdentifier

edit

major · on by default · parameter: a list of names

Reports identifiers matching a list you configure. Useful for retiring a name across a codebase, or banning one that shadows something important.

{ "rules": { "DisallowedIdentifier":
    { "enabled": true, "params": { "targets": ["Result_", "TempVar"] } } } }

fpsonar complains about this

var
  TempVar: Integer;

fpsonar accepts this

var
  PendingTotal: Integer;

The Disallowed* family

edit

Six rules with the same shape: each reports use of something matching a list you supply in targets. They report nothing until you configure them — an empty list means an inert rule.

They exist for migrations and for house bans: retiring a deprecated routine, keeping a legacy type out of new code, forbidding a unit that drags in a heavy dependency. * works as a wildcard.

{
  "rules": {
    "DisallowedRoutine": { "enabled": true,
      "params": { "targets": ["Sleep", "Randomize"] } },
    "DisallowedType":    { "enabled": true,
      "params": { "targets": ["TWideStringList", "TLegacy*"] } }
  }
}

DisallowedRoutine

edit

major · on by default · parameter targets

Reports calls to routines you have banned.

fpsonar complains about this

Sleep(100);                   // with "Sleep" in targets

fpsonar accepts this

Event.WaitFor(100);

DisallowedType

edit

major · on by default · parameter targets

Reports uses of banned types — in declarations, casts and parameter lists.

fpsonar complains about this

var
  L: TLegacyList;             // with "TLegacy*" in targets

fpsonar accepts this

var
  L: TStringList;

DisallowedConstant

edit

major · on by default · parameter targets

Reports uses of banned constants — a magic value that should now come from configuration, for instance.

fpsonar complains about this

Timeout := LegacyTimeout;     // with "LegacyTimeout" in targets

fpsonar accepts this

Timeout := Config.Timeout;

DisallowedField

edit

major · on by default · parameter targets

Reports uses of banned fields. Useful when a field is being replaced by a property and you want the direct accesses found.

fpsonar complains about this

Obj.FLegacyName := 'x';       // with "FLegacyName" in targets

fpsonar accepts this

Obj.Name := 'x';

DisallowedProperty

edit

major · on by default · parameter targets

Reports uses of banned properties.

fpsonar complains about this

Log(Obj.LegacyCaption);       // with "LegacyCaption" in targets

fpsonar accepts this

Log(Obj.Caption);

DisallowedEnumValue

edit

major · on by default · parameter targets

Reports uses of banned enumeration values — a state you are removing from a state machine, for example.

fpsonar complains about this

if Status = stLegacyPending then     // with "stLegacyPending" in targets
  Wait;

fpsonar accepts this

if Status = stPending then
  Wait;

TrackTypeAliases

edit

major · on by default · parameter targets

Reports type aliases matching a pattern. This one is for finding rather than forbidding: where has this alias been introduced, and does it still earn its place?

fpsonar complains about this

type
  TBannedAlias = TStringList;   // with "TBannedAlias" in targets

fpsonar accepts this

// use TStringList directly, or give the alias a name that says why it exists
edit

Naming patterns for each kind of declaration are in naming. Declarations nothing uses are in unused code. Banning a unit is DisallowedImportByPath, in units and imports.

See also

edit
  • fpsonar — what fpSonar is, and how to run it

← Back to fpsonar