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.

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/

I’d say “Separation of Responsibilities” is probably my #1. Others here have mentioned that you shouldn’t code for future contingencies, and that’s true, but a solid baseline of Separation of Responsibilities means you’re setting yourself up for future refactors without having to anticipate and plan for them all now. I.E. if your application already has clear barriers between different small components, it’s a lot easier to modify just one or two of them in the future. For me, those barriers mean horizontal layers (I.E. data-storage, data-access, business logic, user-interfacing) and vertical slicing (I.E. features and/or business domains).

Next, I’ll say “Self-Documenting Code”. That is, you should be able to intuit what most code does by looking at how it’s named and organized (ties into separation of responsibilities from above). That’s not to say that you should follow Clean Code. That takes the idea WAY too far: a method or class that has only one call site is a method or class that you should roll into that call site, unless it’s a separation of responsibility thing. That’s also not to say that you should never document or comment, just that those things should provide context that the code doesn’t, for things like design intent or non-obvious pitfalls, or context about how different pieces are supposed to fit together. They should not describe structure or basic function, those are things that the code itself should do.

I’ll also drop in “Human Readability”. It’s a classic piece of wisdom that code is easier to write than it is to read. Even of you’re only coding for yourself, if you want ANY amount of maintainability in your code, you have to write it with the intent that a human is gonna need to read and understand it, someday. Of course, that’s arguably what I already said with both of the above points, but for this one, what I really mean is formatting. There’s a REASON most languages ignore most or all whitespace: it’s not that it’s not important, it’s BECAUSE it’s important to humans that languages allow for it, even when machines don’t need it. Don’t optimize it away, and don’t give control over when and where to use it to a machine. Machines don’t read, humans do. I.E. don’t use linters. It’s a fool’s errand to try and describe what’s best for human readability, in all scenarios, within a set of machine-enforceable rules.

“Implement now, Optimize later” is a good one, as well. And in particular, optimize when you have data that proves you need it. I’m not saying you should intentionally choose inefficient implementations just because they’re simpler, but if they’re DRASTICALLY simpler… like, is it really worth writing extra code to dump an array into a hashtable in order to do repeated lookups from it, if you’re never gonna have more than 20 items in that array at a time? Even if you think you can predict where your hot paths are gonna be, you’re still better off just implementing them with the KISS principal, until after you have a minimum viable product, cause by then you’ll probably have tests to support you doing optimizations wolithout breaking anything.

I’ll also go with “Don’t be afraid to write code”, or alternatively “Nobody likes magic”. If I’m working on a chunk of code, I should be able to trace exactly how it gets called, all the way up to the program’s entry point. Conversely, if I have an interface into a program that I know is getting called (like, say, an API endpoint) I should be able to track down the code it corresponds to bu starting at the entry point and working my way down. None of this “Well, this framework we’re using automatically looks up every function in the application that matches a certain naming pattern and figures out the path to map it to during startup.” If you’re able to write 30 lines of code to implement this endpoint, you can write one more line of code that explicitly registers it to the framework and defines its path. Being able to definitively search for every reference to a piece of code is CRITICAL to refactoring. Magic that introduces runtime-only references is a disaster waiting to happen.

As an honorable mention: it’s not really software design, but it’s somethign I’ve had to hammer into co-workers and tutorees, many many times, when it comes to debugging: “Don’t work around a problem. Work the problem.”. It boggles my mind how many times I’ve been able to fix other people’s issues by being the first one to read the error logs, or look at a stack trace, or (my favorite) read the error message from the compiler.

“Hey, I’m getting an error ‘Object reference not set to an instance of an object’. I’ve tried making sure the user is logged in and has a valid session.”

“Well, that’s probably because you have an object reference that’s not sent to an instance of an object. Is the object reference that’s not set related to the user session?”

“No, it’s a ServiceOrder object that I’m trying to call .Save() on.”

“Why are you looking at the user session then? Is the service order loaded from there?”

“No, it’s coming from a database query.”

“Is the database query returning the correct data?”

“I don’t know, I haven’t run it.”

I’ve seen people dance around an issue for hours, by just guessing about things that may or may not be related, instead of just taking a few minutes to TRACE the problem from its effect backwards to its cause. Or because they never actually IDENTIFIED the problem, so they spent hours tracing and troubleshooting, but for the wrong thing.

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

Cut the problem into tiny pieces, then group it back together with nice clean connections

Code in nice straight lines. Like good cable management - behaviors should flow from cause to effect, and as much as possible should flow through the main channels

Decide how you organize things, and stick to it. When you see code you don’t remember writing, you should be able to say “if I were me, how would I do this?” and immediately know the correct answer

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

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!

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

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.

• 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

Object orientation

(I’m a java fanatic)

Porn is free.

• Solve the problem directly in front of you. You are not as good at predicting the future as you think you are. (aka: YAGNI)

• Organize your code around the problem domain, and name things accordingly. As a basic razor, consider someone seeing your codebase for the first time – they should be able to easily glean what your app does, not just what language (Java) or frameworks (Rails) or design patterns (MVC) you might be using.

• Each function must Do One Thing. And yes, each test case is a unit, too.

• It must be clear to someone reading a function call what is expected to happen. Only use positional arguments when this is true and when order matters and is reasonably intuitive. Otherwise, always use named arguments.

• Your tests must run quickly. Your code must build quickly. Your CI/CD pipelines must be measured in seconds, not minutes or hours.

• Take nothing for granted. Declare all dependencies, and avoid implicit globals.

• Use a linter, and enforce compliance. It doesn’t matter what the rules are, but once established, avoid changing them.

• Never isolate yourself from your team for too long. If you’re working on a multi-day implementation, check in with the people who would be reviewing your code at least every couple of days. The longer you isolate, the more exhaustion and conflict you can expect during review, for both you and your reviewers.

• Learn to work iteratively, validating minimal implementations that fall short of the full feature as requested, but which build up to it. As opposed to One Big Release. It helps everyone to experience and validate early and often how the feature feels and whether it’s the right direction.

• Never rush. Always take the time to build properly. Your professionalism and expert opinion is non-negotiable, even if (especially if) there’s a deadline. I’m not saying to say “no” – rather, just give honest estimates and offer functional compromises or alternatives when possible. Never “try” to do more than is reasonable.

A lot of this, I attribute to Martin’s books (“Clean Code” and “The Clean Coder”) and his Laracon talk from several years ago (you can find it on YouTube).

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