Coding Standards That Improve Quality

A presentation by @stuherbert  for @GanbaroDigital Coding Standards That Improve
Quality

Industry veteran: architect, engineer, leader, manager, mentor F/OSS contributor since
1994 Talking and writing about PHP since 2004 Chief Software Archaeologist Building Quality @GanbaroDigital About Stuart

Follow me I do tweet a lot about non-tech stuff
though :) @stuherbert

@GanbaroDigital ?? ?? Do you follow any written coding standards?

@GanbaroDigital ?? ?? What do you follow?

@GanbaroDigital ?? ?? Have you written your own?

@GanbaroDigital Let's Slay Some Dragons!

@GanbaroDigital QA Teams

@GanbaroDigital ?? ?? Do you have a QA team?

@GanbaroDigital ?? ?? What do they do?

@GanbaroDigital “ You don't pass code to a QA team
to add quality.

@GanbaroDigital A QA team is an audit function. It assesses
the quality you've already delivered.

@GanbaroDigital “ QA teams don't assess code quality. They assess
outcome quality.

@GanbaroDigital “ You can't outsource quality to a team that
doesn't do construction.

@GanbaroDigital Construction is done by developers.

@GanbaroDigital Coding standards are virtual building regulations.

@GanbaroDigital “Requirements deﬁne what is built. Coding standards (help) deﬁne
how it is built.

@GanbaroDigital Coding standards are part of your engineering manual.

@GanbaroDigital But they don't always improve quality ...

@GanbaroDigital PSR-2

@GanbaroDigital https://www.php-ﬁg.org/psr/psr-2/

@GanbaroDigital A Quick Breakdown of PSR-2

@GanbaroDigital ?? ?? How many requirements are in PSR-2?

@GanbaroDigital 96 Requirements in PSR-2

@GanbaroDigital • MUST • MUST NOT • REQUIRED • SHALL
• SHALL NOT • SHOULD • SHOULD NOT • RECOMMENDED • MAY • OPTIONAL PSR-2 Keywords

@GanbaroDigital PSR-2 Keywords Count 0 17.5 35 52.5 70 MUST
MUST NOT SHOULD SHOULD NOT MAY

@GanbaroDigital Some important caveats ...

@GanbaroDigital PSR-2 Analysis Caveats • Stronger keywords (MUST) can appear
wrapped inside weaker keywords (MAY) • PSR-2 contains duplicate requirements • Some PSR-2 requirements are enforced by the PHP runtime

@GanbaroDigital PSR-2 And Addressing Quality

@GanbaroDigital ?? ?? How much of PSR-2 directly prevents defects
in your code?

@GanbaroDigital PSR-2 Requirements That Prevent Defects 0 17.5 35 52.5
70 MUST MUST NOT SHOULD SHOULD NOT MAY

@GanbaroDigital Defect-Preventing PSR-2 Bits 1. Visibility MUST be declared on
all properties and methods (x3) 2. The closing ?> tag MUST be omitted from ﬁles containing only PHP. 3. There MUST be a comment such as // no break when fall- through is intentional in a non-empty case body

@GanbaroDigital “ Only 5.2% of PSR-2 directly addresses quality.

@GanbaroDigital What Is PSR-2?

@GanbaroDigital ?? ?? What are the other 91 requirements in
PSR-2 all about?

@GanbaroDigital “ PSR-2 is a code formatting standard.

@GanbaroDigital “ PSR-2 is a social standard.

@GanbaroDigital Can consistent formatting improve quality? Yes and no.

@GanbaroDigital It reduces the required reading age (so to speak).
That can make code more accessible as average industry experience declines.

@GanbaroDigital It's an example of the industry learning from the
mistakes of Perl.

@GanbaroDigital It also leads to reduced comprehension because of how
we learn to read prose.

@GanbaroDigital “ Keep using PSR-2 as your code layout standard.
Stop using PSR-2 as your code quality standard.

@GanbaroDigital PSR-2 Replacement

@GanbaroDigital https://github.com/php-ﬁg/ﬁg-standards/blob/master/ proposed/extended-coding-style-guide.md

@GanbaroDigital Is the upcoming PSR-2 replacement any different?

@GanbaroDigital Draft PSR-2 Replacement Keywords Count 0 22.5 45 67.5

@GanbaroDigital 138 Requirements in the current draft

@GanbaroDigital PSR-2 Requirements That Prevent Defects 0 22.5 45 67.5

@GanbaroDigital Draft PSR-2 Requirements That Prevent Defects 0 22.5 45
67.5 90 MUST MUST NOT SHOULD SHOULD NOT MAY

@GanbaroDigital Defect-Preventing Draft Bits • The closing ?> tag MUST
be omitted from ﬁles containing only PHP. • Visibility MUST be declared on all properties. • Visibility MUST be declared on all constants if your project PHP minimum version supports constant visibilities (PHP 7.1 or later). • Visibility MUST be declared on all methods. • The body of each structure MUST be enclosed by braces. • There MUST be a comment such as // no break when fall-through is intentional in a non-empty case body.

@GanbaroDigital “ Only 4.3% of the current draft directly addresses
quality.

@GanbaroDigital The decline is down to better drafting.

@GanbaroDigital As it stands today, the PSR-2 replacement is a
better drafted PSR-2. It does not change the scope of the standard.

@GanbaroDigital “ The PSR-2 replacement is not a quality standard.

@GanbaroDigital ?? ?? Have I slain the twin dragons of
QA teams and PSR-2?

@GanbaroDigital Let's look at writing coding standards that do improve
quality.

@GanbaroDigital Writing A Coding Standard For Quality

@GanbaroDigital There's a limit to what you can achieve through
coding standards.

@GanbaroDigital A Worked Example

@GanbaroDigital Priority Key ID 1.1.1 Category 3-Tier Architecture Criteria Do
not trust higher levels of the architecture. Impacts Security Description Do not assume that any input data is safe. Validate all input data before using it.

@GanbaroDigital Let's break this down.

@GanbaroDigital “ If everything is top priority, nothing is top
priority.

@GanbaroDigital Establish a set of priorities

@GanbaroDigital I Use Three Priority Levels • Key - essential
items • Major - signiﬁcant immediate beneﬁt • Minor - consistency / stylistic / philosophical

@GanbaroDigital Priorities do *not* deﬁne what is mandatory and what
is not.

@GanbaroDigital Everything is mandatory.

@GanbaroDigital Priorities deﬁne where your time goes.

@GanbaroDigital Where Time Goes ... • During development • In
code reviews • On (avoiding!) rework

@GanbaroDigital “ Zero-defect code is perfectly possible. You just can't
afford it.

@GanbaroDigital

@GanbaroDigital In code reviews, everyone checks all Key criteria.

@GanbaroDigital In code reviews, check Major criteria between you.

@GanbaroDigital Minor priorities will need picking up at ﬁrst. Over
time, Minor should become a given.

@GanbaroDigital If they don't, change your criteria or change your
people.

@GanbaroDigital Give every coding standard a unique ID

@GanbaroDigital Unique IDs allow people to communicate more clearly.

@GanbaroDigital IDs are immutable for all time

@GanbaroDigital “ Coding standards are not immutable!

@GanbaroDigital Coding Standards Evolve • Adding new standards • Retiring
obsolete standards • Improving established standards

@GanbaroDigital Immutable IDs prevent confusion as standards evolve.

@GanbaroDigital If the meaning of the standard changes, treat it
as a new standard, allocate a new ID.

@GanbaroDigital Use a structured ID system. e.g. A.B.C A =
priority B = category C = count within category

@GanbaroDigital Structured IDs help you group standards together as they
evolve.

@GanbaroDigital Categories help us see relevant standards together

@GanbaroDigital • API Design • Architecture • Audit Log •
Authentication & Authorisation • Code Health • Common Attacks • Correctness • Documentation • Logical Layering • Persistent Data • Package Management • Naming of Things • Robustness • Session Management • Third Party Packages • Traceability • Unit Testing Example Categories

@GanbaroDigital *not* an exhaustive list!

@GanbaroDigital Categories are concepts / themes that run throughout the
code.

@GanbaroDigital • API Design • Architecture • Audit Log •
Authentication & Authorisation • Code Health • Common Attacks • Correctness • Documentation • Logical Layering • Persistent Data • Package Management • Naming of Things • Robustness • Session Management • Third Party Packages • Traceability • Unit Testing Example Categories

@GanbaroDigital We can review all the standards for a category
and spot obvious gaps.

@GanbaroDigital Criteria tells us what success looks like

@GanbaroDigital Some Example Criteria • Capture all end-user activity in
an audit log. • Always return a JSON object when an error occurs. • Never support a request body in a HTTP GET request.

@GanbaroDigital I use a single sentence.

@GanbaroDigital I use active voice.

@GanbaroDigital I avoid ambiguity.

@GanbaroDigital https://www.gov.uk/guidance/style-guide/a-to-z-of-gov-uk- style

@GanbaroDigital Impacts remind us who/what we are doing this for

@GanbaroDigital (but they're not really 'why' ...)

@GanbaroDigital Impacted functions are a mixture of people and capabilities.

@GanbaroDigital • End-User • The Business • Engineering • Governance
• Regulation • Maintenance • Operations • Platform • Security • Testability Example Impacted Functions

@GanbaroDigital *not* an exhaustive list!

@GanbaroDigital Identify your impacted functions

@GanbaroDigital Description tells you what to do or what not
to do

@GanbaroDigital I use as many sentences as required.

@GanbaroDigital I use active voice.

@GanbaroDigital I avoid ambiguity.

@GanbaroDigital You can go beyond this minimum if time /
budget allows.

@GanbaroDigital Extra Points For ... • Examples • Documenting the
'why'

@GanbaroDigital ?? ?? Is the 'why' optional or mandatory in
a coding standard?

@GanbaroDigital General Guidance

@GanbaroDigital When you look back at your coding standard, is
it SMART?

@GanbaroDigital SMART (in this case!) is ... • Speciﬁc •
Measurable • Actionable • Relevant • Timely

it clear?

@GanbaroDigital Be Clear! • What the standard is • Where
the standard needs applying • Who it impacts • What problem it prevents (the Why) • How important it is to prevent the problem

it necessary?

@GanbaroDigital Is It Necessary? • Does it prevent real or
imaginary problems? • Is it built on (bitter) experience? • Or is it just there to control people?

@GanbaroDigital Do you have buy-in?

@GanbaroDigital Do You Have Buy-In? • Are developers actively maintaining
the coding standard? • Are they actively following it? • Or is it simply imposed by the boss?

@GanbaroDigital “ You cannot ﬁx people problems with technology or
standards.

@GanbaroDigital

Thank You How Can We Help You? A presentation by
@stuherbert  for @GanbaroDigital

Coding Standards That Improve Quality

Coding Standards That Improve Quality

More Decks by Stuart Herbert

Other Decks in Programming

Featured

Transcript