There’s many many important things to consider when writing software; these are just some I find often overlooked and consider particularly important.

PRs for everything

Pull Requests let you:

• Keep main-line branches (develop and/or master) green.
  • Run tests on branches, so we can know the tests pass before code hits main-line rather than fixing things post-hoc.
• Ensure that every change has had a second set of eyes on it.
  • Helps catch mistakes / typos.
  • Ensures that at least two people understand a change, reducing silos of knowledge and helping the understandability of the code.
• Try out new things in a safe environment
  • Think it’d be great if project A didn’t use tool B? Try it out in the safe sandbox of a PR / branch, without affecting anyone else.

GitHub’s “How to write the perfect pull request” is worth a read.

PR early, PR often. Don’t hold off because “it doesn’t work” or you’re not sure if it’s a good idea, or it’s half done, or anything like that. They’re isolated - you’re not going to hurt anything, and it provides a good area for discussion (a prototype is worth a thousand meetings etc.)

If you liked it then you should have put a test on it

(With thanks to Ana Nelson)

I strongly agree with DRMacIver’s Testing Principles.

TL;DR:

• 100% code coverage is mandatory
• All bugs result in tests
• Builds should fail fast
• Principles should never be satisfied by accident
• You need both very general and very specific tests
• Keep trying new ways of testing things
• There is no substitute for hard work

Deployment should be easy

Everybody should understand how to get a code change into production.

The process should be simple, straight forward, and preferably “one button”.

The automated testing should be of a quality where this Just Happens as part of the process.

Deployment should not be “a significant process”, with ritual and ceremony and burning of candles; it should be as much of an unremarkable occurrance as opening your editor or writing a commit.

Feature Flags are awesome

https://speakerdeck.com/simon/feature-flags

Deploying early and often is awesome. Breaking things for customers / giving them half-finished stuff is less so.

Feature flags let us easily go “lets only email staff users and this friendly person with these new notifications” until we’re happy for wider release.

Feature flags let us easily go “oh crap, that’s actually a bit broken, lets turn it off” without actually needing to do a deployment or similar.

Documentation is incredibly important

http://asyncmanifesto.org/

http://www.drmaciver.com/2015/04/things-that-are-not-documentation/

Also, “we use $tool, $tool has docs” does not mean how we use $tool is documented. Make it easy to understand common workflows (“how do I deploy a new version”). Document assumptions / conventions / additions of opinion (“We name our S3 buckets like so”).

Document as close to the thing being documented as possible, to avoid things going stale (if the documentation for an API is in a totally different repo, it’s much easier to forget to keep both in sync), but don’t forget the importance of high-level “how do I use this tool” documentation.

Respect the Principle of Least Astonishment

https://en.wikipedia.org/wiki/Principle_of_least_astonishment

If you have a machine called web and all it runs is Postgres, that is astonishing, please don’t do that (this is also why you shouldn’t call machines things like web…)

If you have a method called get_foo and it writes to the database, that is astonishing, please don’t do that

---

This is in no way exhaustive, nor is it meant to be, but I hope it’s something you find useful, and that it changes the way you develop for the better.