Fpsonar metrics

← Back to fpsonar

Nine rules that count something and complain past a threshold. All are on by default**, and every one has a parameter you are expected to tune — the defaults are** a starting point, not a standard.

These rules differ from the rest of fpsonar in an important way: exceeding a threshold is not a defect. A 200-line routine can be the clearest way to express a 200-step process. Treat a finding as an invitation to look, not an instruction to split.

Tune them in your config:

{
  "rules": {
    "RoutineTooLarge":       { "enabled": true, "params": { "maxStatements": 80 } },
    "CyclomaticComplexity":  { "enabled": true, "params": { "maxComplexity": 15 } }
  }
}

CyclomaticComplexity

edit

major · on by default · parameter maxComplexity

Counts the number of independent paths through a routine — roughly, one plus the number of decisions. It is a rough proxy for how many test cases the routine needs to exercise fully. High values usually mean a long if/case chain that could become a lookup table or separate routines.

fpsonar complains about this

function Classify(A, B, C: Integer): string;
begin
  if A > 0 then
    if B > 0 then
      if C > 0 then Result := 'all'
      else Result := 'ab'
    else if C > 0 then Result := 'ac'
    else Result := 'a'
  else if B > 0 then
    if C > 0 then Result := 'bc' else Result := 'b'
  else if C > 0 then Result := 'c'
  else Result := 'none';
end;

fpsonar accepts this

function Classify(A, B, C: Integer): string;
const
  cNames: array[0..7] of string =
    ('none', 'c', 'b', 'bc', 'a', 'ac', 'ab', 'all');
begin
  Result := cNames[Ord(A > 0) * 4 + Ord(B > 0) * 2 + Ord(C > 0)];
end;

CognitiveComplexity

edit

major · on by default · parameter maxComplexity

Like cyclomatic complexity, but weighted by nesting: a decision three levels deep costs more than one at the top, because a reader has to hold more context. A routine can have modest cyclomatic complexity and still be hard to read if it is deeply nested — this rule is the one that notices.

The usual fix is not fewer decisions but shallower ones: return early instead of nesting the remainder in an else.

fpsonar complains about this

procedure Handle(const AName: string);
begin
  if AName <> '' then
    if FileExists(AName) then
      if CanRead(AName) then
        Process(AName);
end;

fpsonar accepts this

procedure Handle(const AName: string);
begin
  if AName = '' then exit;
  if not FileExists(AName) then exit;
  if not CanRead(AName) then exit;
  Process(AName);
end;

RoutineTooLarge

edit

major · on by default · parameter for the maximum statement count

Counts statements in a routine body. A routine past the limit is usually doing several things that could be named separately.

fpsonar complains about this

procedure Run;
begin
  // ... 200 statements doing parsing, then validation, then writing
end;

fpsonar accepts this

procedure Run;
begin
  Parse;
  Validate;
  Write;
end;

RoutineTooDeeplyNested

edit

major · on by default · parameter for the maximum depth

Counts how deeply blocks nest. Same remedy as cognitive complexity: guard clauses and early exits flatten the shape.

fpsonar complains about this

for I := 0 to High(Rows) do
  if Rows[I].Valid then
    for J := 0 to High(Rows[I].Cells) do
      if Rows[I].Cells[J] <> '' then
        if IsNumber(Rows[I].Cells[J]) then
          Total := Total + StrToInt(Rows[I].Cells[J]);

fpsonar accepts this

for I := 0 to High(Rows) do
begin
  if not Rows[I].Valid then Continue;
  Total := Total + SumNumericCells(Rows[I]);
end;

TooManyParameters

edit

minor · on by default · parameter maxParameters (default 7)

A long parameter list is hard to call correctly — especially in Pascal, where several same-typed parameters in a row can be transposed without the compiler noticing. Group them into a record when the list grows.

Note that factory routines legitimately have long lists, because the parameter list is the data being built. That is a fair reason to accept a finding rather than fix it.

fpsonar complains about this

procedure DrawBox(X, Y, W, H: Integer; ABorder, AFill: TColor;
  ARounded, AShadow, ADashed: Boolean);

fpsonar accepts this

type
  TBoxStyle = record
    Border, Fill: TColor;
    Rounded, Shadow, Dashed: Boolean;
  end;

procedure DrawBox(const ARect: TRect; const AStyle: TBoxStyle);

TooManyVariables

edit

minor · on by default · parameter for the maximum count

Many locals in one routine usually means several distinct pieces of work sharing a scope. Splitting the routine gives each group its own.

fpsonar complains about this

procedure Run;
var
  I, J, K, N, M: Integer;
  S, T, U: string;
  A, B: Boolean;
  L1, L2, L3: TStringList;
begin
  // three unrelated phases, all sharing these
end;

fpsonar accepts this

procedure Run;
begin
  LoadInput;
  Transform;
  WriteOutput;
end;

TooManyDefaultParameters

edit

minor · on by default · parameter for the maximum count

Several defaulted parameters in a row mean most callers pass positional values they do not care about, and adding one in the middle silently changes every existing call. Consider an options record.

fpsonar complains about this

procedure Save(const AName: string; AAppend: Boolean = False;
  AEncoding: TEncoding = nil; ABackup: Boolean = True;
  ACompress: Boolean = False; ARetries: Integer = 3);

fpsonar accepts this

procedure Save(const AName: string; const AOptions: TSaveOptions);

TooManyNestedRoutines

edit

minor · on by default · parameter for the maximum count

Nested routines are useful for a helper used once, but several of them turn the enclosing routine into a small module with no way to test the parts. Promote them to private methods.

fpsonar complains about this

procedure Run;

  procedure Step1; begin end;
  procedure Step2; begin end;
  procedure Step3; begin end;
  procedure Step4; begin end;

begin
  Step1; Step2; Step3; Step4;
end;

fpsonar accepts this

// each promoted to a private method of the class, callable and testable
procedure TRunner.Run;
begin
  Step1; Step2; Step3; Step4;
end;

FileNotTooManyClasses

edit

minor · on by default · parameter for the maximum count

Counts class declarations in one unit. Many classes in a file makes the unit hard to navigate and its uses clause hard to keep honest — every class's dependencies pile into one list.

fpsonar complains about this

unit Model;

type
  TCustomer = class ... end;
  TOrder = class ... end;
  TInvoice = class ... end;
  TShipment = class ... end;
  TPayment = class ... end;
  TRefund = class ... end;

fpsonar accepts this

// one unit per aggregate: Model.Customer, Model.Order, Model.Invoice, ...

A note on counting

edit

What exactly gets counted is not always obvious: whether a case with ten labels costs one or ten, whether and short-circuiting adds a path, whether comment lines count towards a routine's size, whether the hidden Self parameter counts. These answers are pinned by the test suite rather than left to intuition — if a number surprises you, the tests in tests/utstrulesmetrics.pp are the place the answer is written down.

See also

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

← Back to fpsonar