Coding Standards That Improve Quality

Slide 1

Slide 1 text

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

Slide 2

Slide 2 text

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

Slide 3

Slide 3 text

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

Slide 4

Slide 4 text

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

Slide 5

Slide 5 text

@GanbaroDigital ?? ?? What do you follow?

Slide 6

Slide 6 text

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

Slide 7

Slide 7 text

@GanbaroDigital Let's Slay Some Dragons!

Slide 8

Slide 8 text

@GanbaroDigital QA Teams

Slide 9

Slide 9 text

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

Slide 10

Slide 10 text

@GanbaroDigital ?? ?? What do they do?

Slide 11

Slide 11 text

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

Slide 12

Slide 12 text

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

Slide 13

Slide 13 text

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

Slide 14

Slide 14 text

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

Slide 15

Slide 15 text

@GanbaroDigital Construction is done by developers.

Slide 16

Slide 16 text

@GanbaroDigital Coding standards are virtual building regulations.

Slide 17

Slide 17 text

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

Slide 18

Slide 18 text

@GanbaroDigital Coding standards are part of your engineering manual.

Slide 19

Slide 19 text

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

Slide 20

Slide 20 text

@GanbaroDigital PSR-2

Slide 21

Slide 21 text

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

Slide 22

Slide 22 text

@GanbaroDigital A Quick Breakdown of PSR-2

Slide 23

Slide 23 text

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

Slide 24

Slide 24 text

@GanbaroDigital 96 Requirements in PSR-2

Slide 25

Slide 25 text

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

Slide 26

Slide 26 text

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

Slide 27

Slide 27 text

@GanbaroDigital Some important caveats ...

Slide 28

Slide 28 text

@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

Slide 29

Slide 29 text

Slide 30

Slide 30 text

Slide 31

Slide 31 text

@GanbaroDigital PSR-2 And Addressing Quality

Slide 32

Slide 32 text

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

Slide 33

Slide 33 text

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

Slide 34

Slide 34 text

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

Slide 35

Slide 35 text

@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

Slide 36

Slide 36 text

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

Slide 37

Slide 37 text

@GanbaroDigital What Is PSR-2?

Slide 38

Slide 38 text

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

Slide 39

Slide 39 text

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

Slide 40

Slide 40 text

@GanbaroDigital “ PSR-2 is a social standard.

Slide 41

Slide 41 text

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

Slide 42

Slide 42 text

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

Slide 43

Slide 43 text

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

Slide 44

Slide 44 text

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

Slide 45

Slide 45 text

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

Slide 46

Slide 46 text

@GanbaroDigital PSR-2 Replacement

Slide 47

Slide 47 text

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

Slide 48

Slide 48 text

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

Slide 49

Slide 49 text

@GanbaroDigital PSR-2 Keywords Count 0 22.5 45 67.5 90 MUST MUST NOT SHOULD SHOULD NOT MAY

Slide 50

Slide 50 text

@GanbaroDigital Draft PSR-2 Replacement Keywords Count 0 22.5 45 67.5 90 MUST MUST NOT SHOULD SHOULD NOT MAY

Slide 51

Slide 51 text

@GanbaroDigital 138 Requirements in the current draft

Slide 52

Slide 52 text

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

Slide 53

Slide 53 text

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

Slide 54

Slide 54 text

@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.

Slide 55

Slide 55 text

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

Slide 56

Slide 56 text

@GanbaroDigital The decline is down to better drafting.

Slide 57

Slide 57 text

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

Slide 58

Slide 58 text

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

Slide 59

Slide 59 text

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

Slide 60

Slide 60 text

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

Slide 61

Slide 61 text

@GanbaroDigital Writing A Coding Standard For Quality

Slide 62

Slide 62 text

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

Slide 63

Slide 63 text

@GanbaroDigital A Worked Example

Slide 64

Slide 64 text

@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.

Slide 65

Slide 65 text

@GanbaroDigital Let's break this down.

Slide 66

Slide 66 text

Slide 67

Slide 67 text

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

Slide 68

Slide 68 text

@GanbaroDigital Establish a set of priorities

Slide 69

Slide 69 text

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

Slide 70

Slide 70 text

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

Slide 71

Slide 71 text

@GanbaroDigital Everything is mandatory.

Slide 72

Slide 72 text

@GanbaroDigital Priorities deﬁne where your time goes.

Slide 73

Slide 73 text

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

Slide 74

Slide 74 text

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

Slide 75

Slide 75 text

@GanbaroDigital

Slide 76

Slide 76 text

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

Slide 77

Slide 77 text

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

Slide 78

Slide 78 text

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

Slide 79

Slide 79 text

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

Slide 80

Slide 80 text

Slide 81

Slide 81 text

@GanbaroDigital Give every coding standard a unique ID

Slide 82

Slide 82 text

@GanbaroDigital Unique IDs allow people to communicate more clearly.

Slide 83

Slide 83 text

@GanbaroDigital IDs are immutable for all time

Slide 84

Slide 84 text

@GanbaroDigital “ Coding standards are not immutable!

Slide 85

Slide 85 text

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

Slide 86

Slide 86 text

@GanbaroDigital Immutable IDs prevent confusion as standards evolve.

Slide 87

Slide 87 text

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

Slide 88

Slide 88 text

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

Slide 89

Slide 89 text

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

Slide 90

Slide 90 text

Slide 91

Slide 91 text

@GanbaroDigital Categories help us see relevant standards together

Slide 92

Slide 92 text

@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

Slide 93

Slide 93 text

@GanbaroDigital *not* an exhaustive list!

Slide 94

Slide 94 text

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

Slide 95

Slide 95 text

Slide 96

Slide 96 text

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

Slide 97

Slide 97 text

Slide 98

Slide 98 text

@GanbaroDigital Criteria tells us what success looks like

Slide 99

Slide 99 text

@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.

Slide 100

Slide 100 text

@GanbaroDigital I use a single sentence.

Slide 101

Slide 101 text

@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.

Slide 102

Slide 102 text

@GanbaroDigital I use active voice.

Slide 103

Slide 103 text

@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.

Slide 104

Slide 104 text

@GanbaroDigital I avoid ambiguity.

Slide 105

Slide 105 text

@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.

Slide 106

Slide 106 text

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

Slide 107

Slide 107 text

Slide 108

Slide 108 text

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

Slide 109

Slide 109 text

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

Slide 110

Slide 110 text

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

Slide 111

Slide 111 text

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

Slide 112

Slide 112 text

@GanbaroDigital *not* an exhaustive list!

Slide 113

Slide 113 text

@GanbaroDigital Identify your impacted functions

Slide 114

Slide 114 text

Slide 115

Slide 115 text

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

Slide 116

Slide 116 text

@GanbaroDigital I use as many sentences as required.

Slide 117

Slide 117 text

@GanbaroDigital I use active voice.

Slide 118

Slide 118 text

@GanbaroDigital I avoid ambiguity.

Slide 119

Slide 119 text

Slide 120

Slide 120 text

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

Slide 121

Slide 121 text

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

Slide 122

Slide 122 text

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

Slide 123

Slide 123 text

@GanbaroDigital General Guidance

Slide 124

Slide 124 text

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

Slide 125

Slide 125 text

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

Slide 126

Slide 126 text

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

Slide 127

Slide 127 text

@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

Slide 128

Slide 128 text

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

Slide 129

Slide 129 text

@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?

Slide 130

Slide 130 text

@GanbaroDigital Do you have buy-in?

Slide 131

Slide 131 text

@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?

Slide 132

Slide 132 text

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

Slide 133

Slide 133 text

@GanbaroDigital

Slide 134

Slide 134 text

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