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.
Design principles from A philosophy of software design:
- Complexity is incremental: you have to sweat the small stuff
- Working code isn’t enough: Strategic vs tactical programming
- Modules should be deep
- Interfaces should be designed to make the most common usage as simple as possible
- General-purpose modules are deeper
- Different layers should have different abstractions
- Pull complexity downwards: It’s more important for a module to have a simple interface than a simple implementation
- Separate general-purpose and special-purpose code
- Define errors (and special cases) out of existence
- Design it twice
- Comments should describe things that are not obvious from the code
- Code should be obvious: Software should be designed for ease of reading, not ease of writing
- 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
- 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/.
Top comments (0)