Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Coding Standards That Improve Quality

Coding Standards That Improve Quality

You’ve sat down to do a code review for a pull/merge request. How do you decide whether or not to accept the request? How do you agree amongst yourselves on that? And how to do train others to achieve a consistent level of quality for when they’re doing code reviews too?

In this talk, Stuart will show you a breakdown of PSR-2 - the PHP Community’s main official coding standard - and look at the parts of PSR-2 that directly affect code quality. From there, he’ll present a definition of what quality means, and how to go about writing your own in-house coding standards to achieve consistent quality across all your pull/merge requests.

Presented at Leeds PHP User Group, 20th March 2019.

Stuart Herbert

March 20, 2019
Tweet

More Decks by Stuart Herbert

Other Decks in Programming

Transcript

  1. 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
  2. @GanbaroDigital A QA team is an audit function. It assesses

    the quality you've already delivered.
  3. @GanbaroDigital • MUST • MUST NOT • REQUIRED • SHALL

    • SHALL NOT • SHOULD • SHOULD NOT • RECOMMENDED • MAY • OPTIONAL PSR-2 Keywords
  4. @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
  5. @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
  6. @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
  7. @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 files containing only PHP. 3. There MUST be a comment such as // no break when fall- through is intentional in a non-empty case body
  8. @GanbaroDigital It reduces the required reading age (so to speak).

    That can make code more accessible as average industry experience declines.
  9. @GanbaroDigital “ Keep using PSR-2 as your code layout standard.

    Stop using PSR-2 as your code quality standard.
  10. @GanbaroDigital Defect-Preventing Draft Bits • The closing ?> tag MUST

    be omitted from files 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.
  11. @GanbaroDigital As it stands today, the PSR-2 replacement is a

    better drafted PSR-2. It does not change the scope of the standard.
  12. @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.
  13. @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.
  14. @GanbaroDigital I Use Three Priority Levels • Key - essential

    items • Major - significant immediate benefit • Minor - consistency / stylistic / philosophical
  15. @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.
  16. @GanbaroDigital Coding Standards Evolve • Adding new standards • Retiring

    obsolete standards • Improving established standards
  17. @GanbaroDigital Use a structured ID system. e.g. A.B.C A =

    priority B = category C = count within category
  18. @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.
  19. @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
  20. @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
  21. @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.
  22. @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.
  23. @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.
  24. @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.
  25. @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.
  26. @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.
  27. @GanbaroDigital • End-User • The Business • Engineering • Governance

    • Regulation • Maintenance • Operations • Platform • Security • Testability Example Impacted Functions
  28. @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.
  29. @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.
  30. @GanbaroDigital SMART (in this case!) is ... • Specific •

    Measurable • Actionable • Relevant • Timely
  31. @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
  32. @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?
  33. @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?
  34. Thank You How Can We Help You? A presentation by

    @stuherbert
 for @GanbaroDigital