Permalink
Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
383 lines (277 sloc) 15.5 KB

Developer’s Handbook

Table of Contents

Welcome

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.

Philosophy

“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.

Monolith First

“I see you have a poorly structured monolith. Would you like me to convert it into a poorly structured set of microservices?”

Architect Clippy

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.

Process and Communication

“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.”

Jeff Atwood

If it’s not on Slack or GitHub, it didn’t happen.

GitHub

“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.”

Jeff Atwood

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.

Workflow

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.

Documentation

“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.

Platforms, Languages & Frameworks

We build on open source platforms, languages and frameworks. Examples of these would be Laravel, Node, Go and Rails.

Semantic Versioning

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:

  1. MAJOR version when you make incompatible API changes,
  2. MINOR version when you add functionality in a backwards-compatible manner,
  3. and PATCH version when you make backwards-compatible bug fixes.

Tooling

Build Tools

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.

Text Editor

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.

Testing

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.

Continuous Integration

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.

Monitoring

Before any code is running on a server, all standard monitoring tools must be installed. This includes staging servers.

Exception Tracking

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.

Uptime Monitoring

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.

Server Monitoring

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 :)

Analytics

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.

Launch Policy

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.

  1. Never release anything major on a Friday
  2. Get someone else to test your work
  3. Make sure you are available on release days, don’t make other commitments
  4. 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.

Performance

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.

Finer Details

HTTPS + TLS

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.

10 Reasons To Use HTTPS

Canonical URLs

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

Remote Working

Work Wherever Work gets Done

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.

Must Watch

Must Listen

Must Read

Learning more

We have a paid Laracasts account, use it :)

Zombie Apocalypse

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.

Contributing

This is Your Company. This is Your Book.

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 readme@wearenext.co.za