← 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
editmajor · 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
editmajor · 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
editmajor · 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
editinfo · 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
editinfo · 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
editThe 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
editinfo · 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
editinfo · 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
editinfo · 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);
Related chapters
editComment 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