One principle I try to apply (when possible) comes from when I learned Haskell. Try to keep the low-level logical computations of your program pure, stateless functions. If their inputs are the same, they should always yield the same result. Then pass the results up to the higher level and perform your stateful transformations there.

An example would be: do I/O at the high level (file, network, database I/O), and only do very simple data transformations at these levels (avoid it altogether if possible). Then do the majority of the computational logic in lower level, modular components that have no external side effects. Also, pass all the data around using read-only records (example: Python dataclasses with frozen=True) so you know that nothing is being mutated between these modules.

This boundary generally makes it easier to test computational logic separately from stateful logic. It doesn’t work all the time, but it’s very helpful in making it easier to understand programs when you can structure programs this way.

Zen of python (PEP 20):

Beautiful is better than ugly. Explicit is better than implicit. Simple is better than complex. Complex is better than complicated. Flat is better than nested. Sparse is better than dense. Readability counts. Special cases aren’t special enough to break the rules. Although practicality beats purity. Errors should never pass silently. Unless explicitly silenced. In the face of ambiguity, refuse the temptation to guess. There should be one-- and preferably only one --obvious way to do it. Although that way may not be obvious at first unless you’re Dutch. Now is better than never. Although never is often better than right now. If the implementation is hard to explain, it’s a bad idea. If the implementation is easy to explain, it may be a good idea. Namespaces are one honking great idea – let’s do more of those!

Encapsulation.

Any time i even think I need inheritance, I immediately change it for encapsulation. I’ve never regretted this.

Not clean code - uncle Bob is a hack.

KISS YAGNI DRY in that order.

Think about coupling and cohesion. Don’t tie things together by making them share code that coincidentally is similar but isn’t made for the same purpose.

Don’t abstract things until you have at least 2 (preferably 3) examples of what you’re trying to abstract. If you try to guess at the requirements of the 2nd or 3rd thing you’ll probably be wrong and have to undo or live with mistakes.

When you so abstract and break things down, optimize for reading. This includes maximizing loading the code into your head. Things that make that hard are unnecessary indirections (like uncle Bob tells you to do) and shared state (like uncle Bob tells you to do).

Pure functions (meaning they take inputs and remit outputs without any side effects such as setting shared state) are the platonic ideal. Anything written not as a pure function should have a reason (there are tons of valid reasons, but it’s a good mental anchor)

I should really read the Ousterhout book. It would be great if I could just point people at something, and it sounded decent from that discussion between him and Bob I saw the other day

Edit: I don’t agree with everything in here but it’s pretty great https://grugbrain.dev/

• Low coupling, high cohesion
• Sometimes it’s better to use a less optimized solution for clarity or simplicity
• A simple solution is usually better than a “clever” one
• Allot time for refactoring during development, don’t assume it will be done later (spoiler: it won’t)

I write my code for future maintainers. I optimize for clarity, testability, and readability.

I’ve become a huge fan of dependency injection. That does not mean I like DI frameworks (Guice). I tend to do it manually with regular code.

When I maintain code and I sit there wondering what it actually does, I write a unit test for it right then and there

And so on

Idempotence / self-healing: the system should be built in such a way that it tries to reach the correct end state, even if the current state is wrong. For instance, every time our system gets an update, it will re-evaluate the calculation from first principles, instead of doing a diff based on what was there before. This prevents bad data from snowballing and becoming a catastrophe.

Giving yourself knobs to twiddle in production: at work we have ways of triggering functionality in the system on request. Basically calling a method directly on the running process. This is so, so useful in prod issues, especially when combined with the above. We can basically tell the system “reprocess this action/command/message” at any time and it will do it again from first principles.

Debugging: I always first try and find a way to replicate it quickly. Then, I try and simplify it one tiny step at a time until it’s small enough I can understand in one go. I never combine multiple steps per re-run and always verify whether the bug is there or not at every single stage. This can be quite a slow approach but it also means I am always making progress towards finding the answer, instead of coming up with theories which are often wrong, and getting lost in the process.

When I explore or consider alternatives, I don’t think of or ask myself about design principles, but consider and weigh what could and would make sense where I am.

More than principles, the guiding goal is Maintainability - Readability, Graspability, Consistency, Correctness, Robustness. Weighted against constraints.

I guess separation of concerns is a big one I use implicitly. Like many others.

Single responsibility. I deplore my backend developers who think that just because you’re mauling a single (Java) stream for an extended operation, it’s ok to write a single wall-of-text, 5 lines long, 160 characters wide. Use fucking line breaks, for fuck’s sake!

Don’t design for having a nice codebase today, design for having a clean codebase after 3 months of Devs copy pasting one bit of code then tweaking it to do what they need or adding more fields to existing concepts.

This generally means it’s best to have one pattern for a given thing, rather than having several patterns you pick based on context, the later runs into problems:

• Someone copy/pasted pattern A for a pattern B context
• Enough stuff changes in a pattern A implementation that it would now be better as a patter B thing.

A second consideration for this is that if there are a group of classes/files/whatever that regularly needs to be copied they should live together. If there are different sections of the code that needs to be edited when creating a new resource, they should be kept in one place and kept small-ish.

Most of this comes from accepting the way people tend to work and from the perspective that software is a living evolving process and only regarding a snapshot of it misses vital information.

Destroy abstractions

The reality is, if you have an abstraction layer and one implementation of it, you dont need that abstraction layer

People will complain, “oh but think about the refactor if we have to change vendors/etc” but i have yet to ever switch vendors/api/etc and not had to completely rethink the abstraction layer

Just get rid of it, it will be easier, less code, more precise, and in the long run you’ll cargo cult less

Just write the code for the things you have, and if things change, yup then things will change - to anticipate future changes and upfront the work for the unknown only to then have to make more changes once those real changes eventually arrive and dont match your old predictions is just more work and more confusion

• Talk to your colleagues: clarify requirements, question assumptions, get feedback, talk about best practices and why you do stuff the way you do it
• Single responsibility principle

Common:

• Procedural, preferably Functional. If you need a procedure or function use a procedure or function.
• Object Oriented. If you need an object use an object.
• Modular
• Package/Collection of Modules
• Do not optimize unless you need to.
• Readable is more important then compact.
• Somone said minimal code coupling, Yes! Try to have code complexity increase closer to N then N factorial where N is code size.

Frankly everything else is specialized though not unuseful.

DRY KISS

Software design should minimize work and provide structure.

In practice it’s harder to do the larger a project.

Most strategies work well with a few dozen files, but not tens of thousands of files by hundreds of developers.

Which is exactly what happens now in the average web page