The Neuronen Schmiede concerns itself with topics related to software development. One focus are robust web applications.

Characteristics of Quality Software Projects

Permalink

Following characteristics signal that a software project is in good shape on a technical level. The different traits improve the developer experience and help shipping quality software. They are based on my experience developing and operating web-based applications.

01. List of dependencies

Every dependency has a cost and people working on a system should be aware of this. Therefore it's best to have a list of every dependency and its license. Naturally this includes dependencies of dependencies and everything else needed to operate the system like external services for example.

02. Unified way to run development tasks

A single interface towards common development tasks like running tests, starting the development server, creating and executing database migrations.

03. Single command to start system in development

A single command that starts the application server, background workers and any other additional processes needed to run the system in development.

04. Command to run tests

A single command that runs and verifies all test cases of the project.

05. Command to run only unit tests

A single command that only runs fast unit tests that ensure a short feedback loop and reduce friction when practicing TDD. By definition this command does not run slower acceptance tests that ensure users can actually use the system.

06. Console

A command that starts an interactive console that allows developers to directly interact with the systems components.

07. Deployment

A single command to deploy a new version of the system and run necessary database migrations.

08. Code reload for development

Source code changes automatically restart the development system. Instead of fancy reload strategies and long running processes the entire system is stopped before it’s started again.

09. Single executable for every separate system component

The application server and every other separate component of the system is a single executable so there is no difference between running it in development or production.

10. Customisability of development setup

The command to start the development setup (see point 2.) uses a sensible default configuration for the system. If a developer has reason to deviate from the default configuration it is done in a standardised way.

11. Provide seed data

A configuration option that starts the system with a set of curated seed data. The seed data should cover all major scenarios and use cases covered by the system. It speeds up development, makes edge cases visible and can be used for acceptance tests.

12. Configuration via command line arguments

The configuration for a component of the system is provided via command line arguments. The directness of this approach is to prefer over environment variables or configuration files.

13. Configuration validation at startup

Runtime errors due to a missing or corrupt configuration are prevented by validating the provided configuration at startup.

14. No environment logic inside the application

The application contains no logic based on the environment it is operated in. Required implementation differences like email delivery services are handled via the configuration of the system.

15. SQL database migrations

The database migrations are written in plain SQL instead of a custom framework or programming language syntax.

16. Database schema in SQL

For quick insights the database schema is checked into source control as plain SQL file.

17. Support for background work

A standardised mechanism to move work outside the request response cycle.

18. Logging

The system provides a logger that writes its output to STDOUT.

19. Error tracking

No error is dropped, all components report occurring errors to a central error tracking service.

20. Email delivery

Reliably delivering email is hard, the system delegates this burden to an external service. In non-production situations the emails are sent to a local catch-all server to allow introspection.

21. Templates without logic

It is not possible to transform or access data by accident in templates. The template only takes values and renders the output.

22. Previews of visible system parts

During development and quality assurance all viewable parts are available for preview outside the specific use cases they are part of. This includes web pages, emails, PDFs and other artefacts.