- Welcome
- Philosophy
- Process and Communication
- Documentation
- Platforms, Languages & Frameworks
- Semantic Versioning
- Tooling
- Testing
- Monitoring
- Launch Policy
- Performance
- Finer Details
- Remote Working
- Must Watch
- Must Listen
- Must Read
- Learning more
- Zombie Apocalypse
- Contributing
Welcome to the Next Developer’s Handbook!
This is a living documentation about our best practices, technology stack and development standards. It is important that these guidelines are considered the baseline for new products and services. Deciding against any of these practices should be discussed with your team first. Similarly, if a project grows big enough to warrant new workflows, technologies or systems, please discuss it with your team first.
“Make it work ➤ Make it right ➤ Make it fast”
– DHH
Much of how we work is inspired by the Lean Startup Principles, we love building minimum viable products, measuring, learning and iterating over that cycle.
We love writing beautiful code! Beauty, however, is in the eye of the beholder. For us, beautiful code is code that is simple, sturdy, well tested and works.
“I see you have a poorly structured monolith. Would you like me to convert it into a poorly structured set of microservices?”
Modules, packages, libraries and micro services are all great things but they are not the starting point.
We always take the approach of building monoliths first. Once we understand module boundaries and how the application is structured we can then start destructuring, refactoring and extracting functionality into little pieces if required.
- MonolithFirst — Martin Fowler
- MicroservicePremium — Martin Fowler
- RailsConf 2015 — Opening Keynote
- 10+ Years of Rails with DHH
“Don’t go dark. Don’t be that guy in the room. Hiding your code until it’s “done” may feel safer, but it isn’t.”
If it’s not on Slack or GitHub, it didn’t happen.
“Developers who work for long periods -- and by long I mean more than a day -- without checking anything into source control are setting themselves up for some serious integration headaches down the line.”
Check In Early, Check In Often.
The GitHub News Feed is in some ways the news feed of our company. Don’t work in a vacuum, if the code isn’t checked into source control, it doesn’t exist.
There’s a big difference between broken code and incomplete code. If your code is incomplete work in a branch, nobody is going to judge your work. Incomplete code shows progress, thinking and attempts at implementation. No code shows nothing.
Our projects are usually small enough for the GitHub Flow to work perfectly for us! This keeps things simple as well as inclusive, allowing designers and product owners to collaborate with us :)
If the decision has been made to use a different method of collaboration using Git then please make sure everyone in your team is aware of that.
“A project without documentation is like a project that doesn’t exist.”
– Verbose
The bare minimum, in terms of documentation, is a readme that has instructions for getting a new developer up an running with your project, able to contribute code and get code onto a production or staging server.
Beyond a readme the best kind of documentation you can have is clean code.
If you’re writing code that other people depend on, for example a library or package, then keeping a changelog is a very good idea.
We build on open source platforms, languages and frameworks. Examples of these would be Laravel, Node, Go and Rails.
When writing packages or modules, they must be versioned using Semantic Versioning. We do this to communicate changes to people depending on your code.
Given a version number MAJOR.MINOR.PATCH, increment the:
- MAJOR version when you make incompatible API changes,
- MINOR version when you add functionality in a backwards-compatible manner,
- and PATCH version when you make backwards-compatible bug fixes.
npm install and npm start should be all that’s required to get your
dependencies installed and a development server running.
All of our build tools are written in JavaScript and run on Node, using either Grunt, Gulp or just plain old NPM.
Check out How to Use npm as a Build Tool as an excellent example of keeping things simple.
You’re welcome to use any text editor or IDE that you like, but please ship an EditorConfig file with your project. This will help our different editors play nicely together.
All project tests must run with the npm test command.
Testing is a massive subject, but the important note here is that it is irresponsible of us as professionals to not write tests. We have different preferences as to when we write tests, how to write tests, what we should actually test… but the important thing is that there are tests.
Don’t aim for 100% code coverage, we aren’t launching space rockets here! Try
have at least some integration tests that make sure important routes return
a 200 OK HTTP response code.
Laravel ships with an example test that checks if the home page responds successfully. Having this test setup and running on a continuous integration server is infinitely better than having no tests at all.
Treat each new bug as an opportunity to create a regression test and gradually increase your code coverage.
We use Travis Pro for continuous integration.
CI is mandatory on every project. It should be configured as early on in the project as possible, preferably day one. Even if all that’s happening is linting and style checking – that’s great!
Remember, this isn’t just for us. We often work with external collaborators and have no control over their development environment or tooling.
Before any code is running on a server, all standard monitoring tools must be installed. This includes staging servers.
We use Sentry for tracking exceptions. Make sure to add user information when it’s available. This allows us to be proactive with clients and offer much better customer support.
We use Pingdom for uptime monitoring. Pingdom’s real user metrics are also useful for measuring performance in scenarios where New Relic isn’t available.
Uptime monitoring allows us to proactively communicate with the client about an outage and what we are doing to fix it. This puts a positive spin on what could otherwise be a negative experience.
We use New Relic for server monitoring.
If we’re managing the servers on a project then please make sure New Relic is installed. Forge can do this for you :)
We use Google Analytics for tracking custom events and page views. Make sure you get a tracking code from your product owner. Refuse to launch without one, even on staging.
When we launch, things get real. We can never be 100% certain things will go smoothly for launch so we need to follow a couple of principles for when we launch or release major updates.
- Never release anything major on a Friday
- Get someone else to test your work
- Make sure you are available on release days, don’t make other commitments
- Keep an eye on Sentry notifications and Google Analytics
Plan for outages. Ask your project lead about the design requirements for 4xx/5xx pages and implement them. Test that these pages work and that they will be called in the event of 4xx/5xx errors actually happening.
Make sure everyone is clear as to performance expectations on a project. As a baseline, make sure you’ve tested your project using the following tools and team members are aware of the results as well as bottlenecks or areas of improvement.
Performance is a massive topic, but here are some useful places to start learning and reading up on the subject.
TLS over HTTPS is mandatory on any project that involves user input. It is ultimately the clients call as there is a minor financial cost. It would, however, be unprofessional of us to not educate them of the implications.
- Use the Mozilla SSL Configuration Generator, even if you’ve installed the certificate with Forge
- Test the installation with the Thawte SSL Certificate Checker
- Test browser support using BrowserStack, we have a paid account for this very reason
For canonical urls we use www without trailing slashes.
e.g. http://www.wearenext.co.za/people
To use or not use trailing slashes is a subjective matter. We have decided against using them because they aren’t as aesthetically pleasing, add an extra character to URLs and often lead to extra work in configuring web servers.
Trailing slash or not, either should work, but the incorrect URL should ideally perform a 301 Permanent Redirect to the canonical URL.
http://wearenext.co.za → http://www.wearenext.co.za
http://wearenext.co.za/people/ → http://www.wearenext.co.za/people
We want you to be able to work wherever you’re going to get work done. Next has had a remote working policy since day one. Which you can read about in depth here. But with much freedom comes some responsibility.
- Notice: Tell people in advance when you’re wanting to work remotely
- Communication: Be more communicative than you’d ordinarily be to make up for the fact that we can’t walk past your computer, bump into you at the watercooler or smell your cologne
- Going AFK: Tell us what you’re doing, tell people when you’re stepping away from the keyboard
- Share your work: when it’s work in progress, when it’s done, when it’s not working out
- Save your code – often
Remote working is kind of a new thing for many people who join us, so we wrote a separate remote handbook which you can read about in depth.
We have a paid Laracasts account, use it :)
In case of a Zombie Apocalypse or an equally catastrophic end of world event, you have the freedom to stop working and focus on your survival. We highly recommend the Zombie Survival Guide, get the hardcover, your Kindle’s not gonna last long without electricity.
If you’ve found this book helpful, awesome. If you think there are some additional things we should add to it, even better. We want joining next to be as seamless an experience as possible. To make a suggestion add an issue, or submit a pull request on GitHub. If that’s confusing, send a mail to [email protected]