Fpsonar comments

← Back to fpsonar

Eight rules. Three are about comments that should not be there, two about documentation that should, and three are tracking rules — a different kind of rule that reports information rather than problems.

NoCommentedOutCode

edit

major · on by default

Commented-out code is the worst of both worlds: it takes up space, it goes stale because nothing compiles it, and a reader cannot tell whether it is a note, a work-in-progress or a mistake. Version control already remembers the old version.

fpsonar complains about this

procedure TReport.Build;
begin
  // FLines.Sort;
  // if FCount > 0 then
  //   Normalise;
  DoBuild;
end;

fpsonar accepts this

procedure TReport.Build;
begin
  DoBuild;
end;

NoDisabledCompilerWarnings

edit

major · on by default

A directive that switches a compiler warning off. The warning was telling you something; disabling it hides the message without changing the code. Worse, a file-scope directive keeps hiding it for everything that follows, including code written later.

If a warning is genuinely wrong in one place, disable and re-enable it around that place rather than for the file.

fpsonar complains about this

{$WARNINGS OFF}

procedure Run;
begin
  Process;
end;

fpsonar accepts this

procedure Run;
begin
  {$PUSH}{$WARN 5024 OFF}     // parameter deliberately unused: interface contract
  Process;
  {$POP}
end;

NoDisabledCompilerHints

edit

major · on by default

The same argument for hints. Hints are the compiler's gentlest output — unused variables, unreachable code — and they are usually right.

fpsonar complains about this

{$HINTS OFF}

fpsonar accepts this

// fix what the hint points at, or scope the suppression with {$PUSH}/{$POP}

PublicMethodUndocumented

edit

info · off by default

The FPC contributor convention: every public or protected method carries a single-line // comment above it saying what it does. The comment is for the caller, who should not have to read the implementation to know what the method promises.

Note this is a token-level check — it looks for a comment on the line above the declaration — because PasTree does not attach comments to declarations. Blank lines between the comment and the declaration will therefore break the association.

fpsonar complains about this

type
  TReport = class
  public
    procedure Build;
  end;

fpsonar accepts this

type
  TReport = class
  public
    // Builds the report from the currently loaded lines.
    procedure Build;
  end;

PublicPropertyUndocumented

edit

info · off by default

The same for public and published properties: a short comment saying what the property represents.

fpsonar complains about this

type
  TReport = class
  public
    property Count: Integer read FCount;
  end;

fpsonar accepts this

type
  TReport = class
  public
    // Number of lines currently loaded.
    property Count: Integer read FCount;
  end;

Tracking rules

edit

The three rules below are not looking for mistakes. They report where something occurs**, so you can find it — an inventory rather than a complaint. All are info** severity, and each needs a pattern configured before it reports anything.

TrackComments

edit

info · on by default · parameter: a marker pattern

Reports comments matching a marker you choose — TODO, FIXME, HACK, a ticket number prefix. Useful for a release checklist: what did we leave unfinished?

{ "rules": { "TrackComments":
    { "enabled": true, "params": { "pattern": "TODO|FIXME|HACK" } } } }

this is reported

// TODO: handle the empty case

this is not

// Builds the report from the currently loaded lines.

TrackStringLiterals

edit

info · on by default · parameter: a pattern

Reports string literals matching a pattern. Its real use is auditing: find hardcoded paths, embedded URLs, or anything that looks like a credential before it reaches a release.

{ "rules": { "TrackStringLiterals":
    { "enabled": true, "params": { "pattern": "https?://|password" } } } }

this is reported

Endpoint := 'http://internal.example.com/api';

this is not

Endpoint := Config.Endpoint;

TrackNoSonar

edit

info · on by default

Reports every place a // NoSonar suppression is used. Suppressions are how you tell fpsonar it is wrong about a line — necessary, but each one is a small debt, and they accumulate invisibly. This rule makes them countable.

Worth running occasionally even if you leave the other tracking rules off: a suppression added to silence a rule during a rush is easy to forget.

this is reported

FreeAndNil(P);  // NoSonar - P is a class instance despite the Pointer alias

this is not

FreeAndNil(L);
edit

Comment formatting — trailing whitespace, line length — is in layout. The FPC copyright-header requirement is MissingCopyrightHeader, in FPC source-tree conventions.

See also

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

← Back to fpsonar