In this blog post I share the Guidelines for New Software Projects that we use at Wikimedia Deutschland.
I wrote down these guidelines recently after a third-party that was contracted by Wikimedia Deutschland delivered software that was problematic in several ways. The department contracting this third-party was not the software development department, as since we did not have written down guidelines anywhere, both this department and the third-party lacked information they needed to do a good job. The guidelines are a short-and-to-the-point 2 page document that can be shared third parties and serves as a starting point when making choices for internal projects.
If you do not have such guidelines at your organization, you can copy these, though you will of course need to update the “Widespread Knowledge at Our Department” section. If you have suggestions for improvements or interesting differences in your own guidelines, leave a comment!
Domain of Applicability
These guidelines are for non-trivial software that will need to be maintained or developed further. They do not apply to throw-away scripts (if indeed they will be thrown away) or trivial code such as a website with a few static web pages. If on the other hand the software needs to be maintained, then these guidelines are relevant to the degree that the software is complex and hard to replace.
Choice of Stack
The stack includes programming language, frameworks, libraries, databases and tools that are otherwise required to run or develop the software.
We want
- It to be easy to hire people who can work with the stack
- It to be easy for our software engineering department to work with the stack
- The stack to continue to be supported and develop with the rest of the ecosystem
Therefore
- Solutions (ie frameworks, libraries) known by many developers are preferred over obscure ones
- Custom/proprietary solutions, where mature and popular alternatives are available, are undesired
- Solutions known by our developers are preferred
- Solutions with many contributors are preferred over those with few
- Solutions with active development are preferred over inactive ones
- More recent versions of the solutions are preferred, especially over unsupported ones
- Introducing new dependencies requires justification for the maintenance cost they add
- Solutions that are well designed (see below) are preferred over those that are not
Widespread Knowledge at Our Department
- Languages: PHP and JavaScript
- Databases: MySQL and SQLite
- Frameworks: Symfony Components and Silex (discontinued)
- Testing tools: PHPUnit, QUnit, Selenium/Mocha
- Virtualization tools: Docker, Vagrant
Architecture and Code Quality
We want
- It to be easy (and thus cheap) to maintain and further develop the project
Therefore
- Decoupled architecture is preferred, including
- Decoupling from the framework, especially if the framework has issues (see above) and thus forms a greater than usual liability.
- Separation of persistence from domain and application logic
- Separation of presentation from domain and application logic
- The code should adhere to the SOLID principles, not be STUPID and otherwise be clean on a low-level.
- The applications logic should be tested with tests of the right type (ie Unit, Integration, Edge to Edge) that are themselves well written and not laden with unneeded coupling.
- Setup of the project for development should be automated, preferably using virtualization tools such as Docker. After this automated setup developers should be able to easily run the tests and interact with the application.
- If the domain is non-trivial, usage of Domain-driven design (including the strategic patterns) is preferred