Code quality guide

DRAFT

Prologue

1. Be risk aware. Too perfect code can be a business risk (slow to write, maybe over-designed). Too sloppy code can also be a business risk (hard to maintain and understand). You have to find a balance that is adapted to the current situation and risk analysis, in which code quality becomes a risk mitigation technique.
2. Be humble. LimeSurvey was made by developers from all over the world, with different age, education and experience. Your code might be read by a completely different team ten years from now, in the same way you are now reading code by developers that no longer work with us.
3. Performance matters sometimes, and shouldn't be disregarded completely. In particular, database queries using the ORM and ActiveRecord can be problematic. Some surveys have thousands of questions and hundreds of thousands of responses. Fast response time is also important for a fluid user experience.
4. It's harder to read code than to write code. Don't choose patterns that are easy or fast to write, but that are easy to read.
5. It's easy to forget cross-cutting concerns like translation and security. Keep a mental note.
6. Stress affects code quality. If your stress level is too high to write code with proper quality, take a step back and discuss it with your boss.

Quality

What is quality? Which aspects of quality can be measured?

It's usually easier to get along what is "bad" code than what's "best" code. Blacklist instead of whitelist?

Quality attributes related to code quality:

• Readability
• Testability
• Maintainability
• Performance
• Security

It's better to avoid emotional language when describing code quality, like "clean" or "dirty". Be precise.

Idiomatic code is more readable than non-idiomatic code. What's idiomatic depends on which context or domain you work in. We work in PHP and web application development, and have other idioms than in, say, functional or hardware-close programming.

Some code are "hot spots" - changed often. Those parts should require higher quality than other code.

Risk

todo

Classes

todo

Functions

Functions are one of the fundamental building blocks of programming, so it's important to get it right.

Functions that are part of a class are called "methods", if you want to be formal.

Different types of functions in PHP:

• Functions
• Methods
• Anonymous functions
• Short functions

---

Guidelines:

NB: I'm using "function" as a word for all types of functions in PHP.

• A function should be short enough to be completely readable on one screen
• A function should not have too many arguments; if you have five or more, consider make it a class instead
• A function has a contract with its surrounding environment:
  • Pre-condition: What needs to be true before the function is executed
  • Post-condition: What will be true after the function has returned
  • The first line in the docblock can be one sentence describing the relation between function arguments and its output
    Example
    function foo() {}
• The function name should tell you what it does; docs should tell you why. How is described by the code itself (hopefully).
• Function name can often be verb + noun, like
• If a function is growing too big, it might be better to create a class instead

---

Assertions

todo

---

Looping

todo

Defensive programming and error handling

todo

Documentation

todo

OOP design

todo

The PHP of yesterday

Old idioms and habits that should be abandoned.

Assoc arrays vs DTO

Objects are already passed by reference; arrays are value types

Security

todo

XSS

Database injection

Permissions and roles

Performance

todo

Testing

todo

QA

PHPUnit

TDD

Mocks, can't mock functions, static methods, mocking as a DSL, PHPUnit mocking tools

Pure functions, referential transparency, side-effects

Unit, functional, integration

Don't test the framework; don't test PHP

Static analysis

php -l, CodeSniffer, Mess Detector, Psalm