Programming principles

Originally published on my blog.

This is a list of principles that I respect for trying to write good software.

At the moment it's very rough. I shared it with my team on our internal team Discourse in this raw form. But I figure I might as well share it. Just remember it's a work in progress, I hope I come back and improve it sometime, but I probably won't.

---

12 factor app

Design principles from A philosophy of software design:

1. Complexity is incremental: you have to sweat the small stuff
2. Working code isn’t enough: Strategic vs tactical programming
3. Modules should be deep
4. Interfaces should be designed to make the most common usage as simple as possible
5. General-purpose modules are deeper
6. Different layers should have different abstractions
7. Pull complexity downwards: It’s more important for a module to have a simple interface than a simple implementation
8. Separate general-purpose and special-purpose code
9. Define errors (and special cases) out of existence
10. Design it twice
11. Comments should describe things that are not obvious from the code
12. Code should be obvious: Software should be designed for ease of reading, not ease of writing
13. The increments of software development should be abstractions, not features

Questions for a new technology

A Management Maturity Model for Performance

GitHub repo: webpro/programming-principles

Web API design:

• Nouns are good; verbs are bad
• Plural nouns and concrete names
• Simplify associations - sweep complexity under the ‘?’
• Errors: Use HTTP status codes; Be descriptive
• Versioning APIs - use whole numbers, maintain back versions

I disagree with the advice to “never release an API without a version”. I think a lot of APIs stay on v1 for a very long time, especially if they’re not heavily used or worked on. For this reason, I’d say drop the version number for the first version, and only introduce it when you need to create /v2/.

• Use “limit” and “offset” for pagination
• Indicate output format with a “filename” suffix (e.g. “.json”)
• Use “?q=” for global search
• Use an “api.” subdomain
• Use the API facade pattern See also: wikipedia