Skip to content

Docs: StyleGuide.md as single source of truth for coding style - #101

Open
omonien wants to merge 1 commit into
MHumm:developmentfrom
omonien:docs/style-guide
Open

Docs: StyleGuide.md as single source of truth for coding style#101
omonien wants to merge 1 commit into
MHumm:developmentfrom
omonien:docs/style-guide

Conversation

@omonien

@omonien omonien commented Jul 23, 2026

Copy link
Copy Markdown

Summary

  • Adds Docs/StyleGuide.md as the single source of truth for DEC coding style, structure, and contribution expectations for new / rewritten code.
  • Consolidates former scattered notes from CONTRIBUTING.md, DEC65.pdf §3.7.1 (structure & style), de-facto library conventions (DEC… units, Apache headers, FPC/Delphi uses), and adapted practices from the modern Delphi Style Guide (naming prefixes, formatting, XML docs).
  • Reworks CONTRIBUTING.md into a short process entry point that points at the style guide.
  • Updates readme.md so contributors find the style guide next to the other project docs.

Policy (explicit)

  • No production / existing source reformatting in this PR (docs only).
  • New code and substantial rewrites (including future feature PRs such as ChaCha re-land) should be reviewed against Docs/StyleGuide.md.
  • Algorithm how-to (DEC65.pdf §3.7.2+) stays in the PDF; when the PDF is next regenerated, §3.7.1 can shrink to a pointer at Docs/StyleGuide.md.

Test plan

  • Docs-only review: read Docs/StyleGuide.md for DEC fit (FPC, unit naming, headers).
  • Confirm CONTRIBUTING.md and readme.md links resolve.
  • No .pas / build changes — nothing to compile.

Introduce a compact DEC style guide consolidating CONTRIBUTING rules,
DEC65.pdf section 3.7.1 structure notes, de-facto library conventions,
and adapted Delphi Style Guide practices. Point CONTRIBUTING and readme
at the guide; enforce for new/rewritten code only, without reformatting
existing sources.
@omonien
omonien force-pushed the docs/style-guide branch from af6cff9 to f10a90b Compare July 27, 2026 09:17
@MHumm

MHumm commented Sep 7, 2026

Copy link
Copy Markdown
Owner

I'm currently reading the styleguide, as far as I am it's mostly good. Eight things:

  1. What does re-lands in "donor re-lands such" mean?

  2. This example
    '''procedure TExample.DoWork(const AValue: string);
    begin
    if AValue = '' then
    raise EDECException.Create('Value required');

if IsReady then
begin
Process(AValue);
end;
end;'''

Is not too clever. In this example I wouldn't wrap Process(AValue); in begin / end, as this is simply unnecessary.
We should put at least another command in this begin / end block and describe that such a single call shouldn't get wrapped as that's simply superflous.

  1. I would ammend this one like shown here: Non-portable code | Wrap in {$IFDEF} so FPC (or unsupported platforms) do not see it. Use DECOptions.inc as the central place for turning on/off specific defines you added.
    So it's clear where such defines like classregistration etc. should be turned on/off/"defined".

  2. I wouldn't write "avoid withs". I would simply forbid it ;-) We're not C-programmers trying to save each keypress ;-)

  3. The list of Type and Interface prefixes misses simple type, e.g. if somebody declares TIndex = Integer the T prefix should be used as well, not only for records.

  4. If we mention this: Record public fields have no F prefix (they are part of the value layout). we would mention this for other public fields as well. Where's the value of this sentence? No Public field should have a F prefix. If the word itsself starts with F this is kept of course. Example: property FileName: string...

  5. Constants: Where was this one deduced from? String constant | sc | scInvalidNonce
    There are some string constants starting with sC, but only because the 1st word of the constant is Cipher.
    sCipherSomething... So I'd change this to string constants start with s.

  6. The example in Documentation comments does not describe AInitVector. For some it might be an obvious parameter for others it might not be (e.g. folks new to cryptography) so it would be better to have a rule to document all parameters.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants