Object Pascal Clean Code Guidelines Proposal (at EKON 22)

Clean Code – Guidelines Proposal
Arnaud Bouchez – Synopse / LiveMon
CLEAN CODE
Guidelines Proposal

Arnaud Bouchez
– Delphi / FPC
• Various solutions (from Vatican to gaming industry)
• IoT solution (RSI)
• Real-time Monitoring solution (LiveMon)
– Open Source
• mORMot (SOA ORM MVC framework)
• SynPDF SynMustache SynDB SynCrypto
– Training and consultancy
• Synopse one-man company

Clean Code Guidelines Proposal
• Guidance
• Target
• Repository
• Code Formatting
• Types definition

Guidance Proposal
• We focus on Server-Side code
Client side is more expandable
• We wonder not only HOW but WHY
Even if coding is an art form,
it is sadly not yet in the modern art market
so most employers don’t care about code

Guidance Proposal
• Proposal
There is no single policy to rule them all
This session should be interactive
Some proposals may not fit your needs
Some proposals may hurt you

Guidance Proposal
• Proposal
There is no single policy to rule them all
This session should be interactive
Some proposals may not fit your needs
Some proposals may hurt you
- at least let’s try to understand
each one point of view

Guidance Proposal
• Proposal
Start from the current LiveMon Guidance
(because I wrote it)

Guidance Proposal
• Proposal
(because I wrote it
and because you will help me improve it)

Guidance Proposal
• Proposal
but this is a work-in-progress
→ make yourself your idea!

Guidance
• Team work needs some rules
especially for our most valuable asset:
use the source, Luke!
- your padawans will thank you

Guidance
• Ease maintainability and interoperability
don’t write for yourself
eventually help yourself

Guidance
• Ease maintainability and interoperability
as if the final maintainer of your code
would be a psychopath
knowing your personal address

Guidance
• Goal: fails at compile time
or fails at code peer review
to avoid (some/most) errors at runtime
Runtime errors are the worse to fix
• Test-Driven Design
Testing is (the main/worse) part of writing

Guidance
• Up to Domain-Driven Design
The Domain code is isolated from
all dependencies (e.g. DB or applications)
→ non technical domain experts
should be able to read, understand and validate
the Domain source code

Guidance
• SOLID Principles
Single Responsibility Principle
Open Closed Principle
Liskov Substitution Principle
Interface Segregation Principle
Dependency Inversion Principle
are Out Of Scope of this presentation
(but worth a full session or workshop)

Compiler Target
• For which Compiler and OS (eventually)
Delphi
FPC
others (TMSWebCore, SMS, EWB…)

Compiler Target
• Isolate OS and compiler specific code
don’t abuse of {$ifdef…}
use a leading {$I conditionals.inc} file
isolate in specific units

Compiler Target
• Isolate OS and compiler specific code
use third party libraries
use shared syntax e.g. FPC {$mode Delphi}
with automated testing on all targets

Compiler Target
• Third Parties
Well identified and chosen
Documented as such
Part of the source code tree (or as external)
Stability in the long term
Cross-OS and Cross-compilers support

Compiler Target
• Static linked C code or raw asm
Sometimes needed for performance
Always with “pure pascal” fallback
Includes documentation
Includes script to rebuild from C sources

Source Code Repository
• As part of the Code requirements
Where and how
we maintain the source code
is part of daily development work
but also of the whole solution design

• Git / Mercurial / Bazar / Fossil / SVN …
Centralized or Distributed
Local copy or Fork/Branch
In-house hosted or Cloud PaaS
• Linked with other tools
Documentation, Project management,
Issues, Support, CRM…

• As part of the Code requirements
main branch should always compile
and pass the regression tests
on all supported platforms
• Continuous Integration
Automated Commit – Build – Test cycle

• Branches and Forks
Per-feature branches on distributed SCM
e.g. git/fossil/bazar
Pull requests with explicit review
before merge by team leaders
Continuous Integration from branches

• Folders Hierarchy
Source code may be project-oriented:
one folder per project + “common” units
(this is a typical layout)

• Folders Hierarchy
Why not use them
to uncouple the logic
and avoid dependencies?
e.g. split data, logic, tests and UI

• Folders Hierarchy at LiveMon
data
daemon
ext
serv
test
tools
ui

• Folders Hierarchy at LiveMon
data daemon ext serv test tools ui
Unit names follow the folder name
e.g. DataMetrics.pas is located in Data
TestAll.dpr is located in Test
DaemonShopMain.pas is located in Daemon

• Sensitive code and files
(private keys, default passwords…)
are better stored outside the repository
(especially on PaaS like github)

• Dependencies
are hosted in several repositories
External dependencies for 3rd parties
Internal dependencies for cross-teams work

• Test-Driven Design are part of the source
Unit tests & Integration tests
to avoid regressions and enhance agility
as part of the integration, or stand-alone
on staging/pre-prod environment

• Test-Driven Design are part of the source
Performance / load stressing tests
if it matters on customer side
as part of the integration, or stand-alone
on staging/pre-prod environment

• Documentation as Code
Reference material as .md files
maintained in synch with the source
complementary to comments
sometimes generated from source
(e.g. mORMOt SOA API via Mustache template)

• Documentation as Code
Reference material as .md files
duplicated in a semi-public “doc” repo
(e.g. for support people, or front-end dev)

• Infrastructure as Code
Automate Containers
– virtualized cloud-based hosting
– containers defined as code
– work with IT to generate (or host) scripts

• Infrastructure as Code at LiveMon
Daemons services endpoints (IP, ports, URI)
are all defined in shared pascal code
– favor convention over configuration
– favor logical over physical
– pascal as expressive script language

– auto-configuration even on barebones servers
– ease scaling and testing
– work with IT to generate (or host) scripts
e.g. with Mustache templates, or internal REST services

Code Formatting
• Define some canonical rules
The most sensitive: begin … end blocks,
nested if … then, naming conventions
Avoid blank lines (refactor in methods)

Code Formatting
Use some reformatting tool
CnPack, Castalia, …
will make all team members aware of it
As part of review step (or commit?)

Code Formatting
https://blog.golang.org/go-fmt-your-code
“easier to write, read and maintain
and uncontroversial”

Code Formatting
Comments
not revision history – use a SCM
not (****) – use regions
as specs = as valuable as code

Code Formatting
But this is not the main point,
since formatting is a matter of
convention, not logic

Types Definitions
• Follow Common Delphi Convention
TCamelCase
ISomeInterface
TSomeEnum = (seOne, seTwo…);
TOnSomeEvent = procedure of object;
CONSTANT_NUMBER

Types Definitions
• No Hungarian Notation
TSomeCounterInteger
SOMEVALUE_KONST
ParameterInput
sounds like polluting the modelization
→ rather use the IDE features

Types Definitions
• Class definition
TMyClass = class(TOtherClass)
private
fSomeProperty: TSomeType;
public
property SomeProperty: TSomeType read…

Types Definitions
private
function GetSomeProperty: TSomeType;
public
property SomeProperty: TSomeType read…

Types Definitions
use myclassvar.fSomeProperty
or myclassvar.GetSomeProperty
myclassvar.SetSomeProperty()
to make method calls explicit
for internal calls

Types Definitions
private
published
property someproperty: TSomeType read…
(when JSON serialized for JS API)

Types Definitions
follow SOLID principles, mainly:
smaller dedicated classes
favor composition over inheritance
abstraction via interfaces
as few unit dependency as possible

Types Definitions
• Naming is modelizing
Follows the modelized reality, not the tech
cf. DDD Ubiquitous Language
e.g. TInvoiceTotalValue
not double
not TSQLSumResult

Types Definitions
• Naming is about grammar
method = verb in infinitive form
event or enumerate = verb in past form
variable = reality name
(or verb in past form for counts/boolean)

Types Definitions
method = SendEmail()
event or enumerate = eeEmailSent
variable = TEmailTitle, EmailWasSent

Types Definitions
method = Email()
event or enumerate = eeSuccess
variable = Text, ok

Types Definitions
• Naming is about meaning
i.e. reading the code should be as close as
reading the logic in plain English
→ avoid technical or anemic model

Types Definitions
i.e. reading the code should be as close as
reading the logic in plain German
→ avoid technical or anemic model

Types Definitions
method = SMTPExecute()
event or enumerate = 200
variable = s, b

Types Definitions
• Enumerations
are a very powerful feature of pascal
convenient way to modelize state or errors
you could use RTTI to retrieve text (logs)

Types Definitions
• Enumerations
by convention, first (=0) item is success
especially with stubs/mocks

Types Definitions
• Enumerations
convenient way for compile-time errors
e.g. when defining DTOs
const
CONV: array[TDomainEnum] of TAppEnum =
(….);

Types Definitions
• Naming is about consistency
once you defined some rules, stick to them
procedure MyMethod(param: integer);
procedure MyMethod(Param: integer);
procedure MyMethod(aParam: integer);

Types Definitions
• Naming is about consistency
once you defined some rules, stick to them
var Current: TEmailSender;
var current: TEmailSender;

Types Definitions
• Naming is absolute in public
but it won’t hurt to use i,j,k for local loops
(or the for item in items do syntax)
local variables may be named according
to the technical implementation context

Types Definitions
• Strongly-Typed Pascal
var a: integer;
begin
a := ‘text’;
end.

Types Definitions
var a: integer;
begin
a := ‘text’; // fails to compile
end.

Types Definitions
JavaScript is (was) not
so TypeScript, Dart, Flow, … appeared
to write and maintain big projects

Types Definitions
not only classes or records, but also
type
TDistanceMeters = type double;
TDistanceMiles = type double;

Types Definitions
type
it won’t be slower, but could be much safer!

Types Definitions
type
Make the Implicit Explicit !

Types Definitions
function CalculateTrajectory(
altitude: double): TTrajectory;
Avoid another Mars Climate Orbiter failure!

Types Definitions
function CalculateTrajectory(
altitude: TDistanceMeters): TTrajectory;
Avoid another Mars Climate Orbiter failure!

Types Definitions
• Exceptions should be exceptional
Some languages don’t implement them
https://golang.org/doc/faq#exceptions
use Exception in “panic” mode
when DB or network is down, disk is full,
dead branch is reached in code…

Types Definitions
Severity is hidden
Is it an user input entry error, or a DB failure?
Not easy to transmit remotely
Exceptions are classes with no persistence
and sometimes some pointers to context

Types Definitions
Performance cost
On all platforms
Not debugger-friendly
Did you try to debug Indy calls in the IDE?

Types Definitions
Rely on Error Codes
Dedicated Enumerations
Optionally with some text for UI
Complex errors may return a class/record
But not the same class as on success

Types Definitions
Don’t rely on HTTP status codes
Logic should be uncoupled from HTTP
What if you execute the code locally?
Only if you really need it
e.g. when implementing a standard

Types Definitions
Log and transmit all exceptions
On heavily loaded servers, it would save
you a lot of time filtering real problems
Too much notification is killing the notification!

Clean Code
i. From consensus comes success
ii. Don’t pollute your code – hide technical
iii. Naming is everything
iv. Code should be like natural language
v. Make the implicit explicit
vi. Exceptions should be exceptional
vii. ….

• Questions?
Clean Code Guidelines Proposal

Object Pascal Clean Code Guidelines Proposal (at EKON 22)

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Similar to Object Pascal Clean Code Guidelines Proposal (at EKON 22)

Similar to Object Pascal Clean Code Guidelines Proposal (at EKON 22) (20)

More from Arnaud Bouchez

More from Arnaud Bouchez (20)

Recently uploaded

Recently uploaded (20)

Object Pascal Clean Code Guidelines Proposal (at EKON 22)