OK, I know, a bit egocentric to name a law after yourself, but here goes. It applies in all kinds of places, but it's really for the most part a Software Development law.
Architecture is persistent.
The moment you sit down and start writing code, you're laying down the architecture for your software. It doesn't matter what you write, it has infrastructure. All code is infrastructure, with other code that does something to the data. Most of the code you will ever write is spent navigating that infrastructure to gather data and perform operations on it, and then store that data out.
This gives us a number of interesting little results that you see in the real world all the time:
Once you write some code, the architecture you decided on sticks around.
Seriously. The more code you write, the more the architecture you specified becomes embedded in every piece of code you write. You can't help it - it's part of the code's DNA. Every choice you make will pervade everything your code does forevermore.
For example... You write a large piece of code which has a scripting system which is used for everything - header generation, you name it. Script based objects are garbage collected.
Now, later, you decide "Hey, wait a minute... this GC is slowing me down... the script language isn't completely fleshed out so it's hindering me, and it's not suitable for all of the tasks I envisioned at the start".
Tough cookies. At this point, a year later, you now have so much code written based on this architecture, that even if you find ways around it, your code will still taste of the existing architecture. You can refactor all you want, but until you deliberately start a second branch of code that is an isolated and sterile environment, that only talks to the original code through very hard specified APIs - kind of a software firewall - you'll have that architecture still. Even if you rip out every single line of code that uses the original architecture, unless you effectively develop the new code in a vacuum, your code will still have that architecture embedded deep inside it.
People who have worked on large projects involving 3rd party code which doesn't work as advertized should recognise this one.
If you don't specify an architecture, you get one anyway.
It might not be the architecture you want, but it's certainly an architecture. The problem is that the code will generate structure as it goes, and that structure is architecture. It'll persist just as much as the original architecture, and all you can hope for is that this hackery wasn't part of your main code path. (Which means you might, just might, be able to snip it out).
Never write code ad hoc. Always at least spend a moment thinking about the architecture of the code you're writing. If you're dealing with 3rd party code, try to analyze the architecture of their system before committing your own code to it - misunderstanding their design is bad, as you'll end up creating incompatible architecture around it, and doubling your work - you'll have wrapper code which does more than it needs to, and then that'll spawn its own kind of architecture.
If you're dealing with 3rd party code which hasn't got any architecture, and was developed ad hoc, you're kind of screwed. It'll be difficult to get the architecture to sit in your brain.
Most software development - from a human perspective - is the building of abstract models of how something works. The easier this is for someone, the more easily used that code will be. If your architecture is clean, easy to understand, logical and consistent, it'll sit well in someone else's brain because the number of details they need to remember goes down rapidly. They don't have to remember all of the function names in your code, or all of the nitty gritty details. All they need to remember is roughly what shape that code has (its model), and how that relates to other similar code they've seen, and other design patterns they've experienced.
Take WxWindows. It shares a number of architectural similarities with ATL Windowing code, WTL, MFC and .NET Windows Forms. (Personally, I don't like working with it as much as any of the aforementioned libraries because of a variety of reasons, but that's besides the point). This means that anyone with experience in Win32 UI development should be able to very quickly pick up WxWindows programming. The models are the same - the architecture is similar. Basically, it's a message passing system, with event hooks, and some resource handling for the creation of controls. The function names may be different, and some of the implementation details may change, but for the most part it's an easily understood model - because it's a similar model to other environments.
Things that can make code easier to understand for other engineers tend to also be things that give a solid architectural base:
- Design your code first. Make a laundry list of the different things you're going to need to make your app, and figure out how you want to handle everything on that list. It should be as exhaustive as possible. You can always add later, but you want to be able to find any fundamental architectural pieces that you need to implement so that the rest of your code will use it consistently. You don't want any surprises.
- Try to write code from the top down. When writing any class, decide how you - as a programmer - would want to write code against that class. Write that code first. Then write the class to fit. Stub out functions if you need to (but make sure you mark them so that you know you need to finish them up).
- Write comments at the function and class level. These describe the model you're using, and separate out implementation specific details (eg. how exactly you write a serialization function) from the structure of the application (ie. the fact that it actually performs serialization in a standardized fashion).
- Once you've decided on a pattern for handling a scenario in your code, stick with it. Don't alternate patterns. For example, if you return error codes in one place, return them everywhere. Don't switch to exceptions somewhere else. If you need to use them, wrap them in a try catch at the lowest level you can, and return an error code as a result.
- Read as much code as you can. Try to find out what works well, and what doesn't. More importantly, try to understand if there was a good reason behind the way that code was written, or if it was created ad hoc.
Other programmers aren't stupid. They tend to be smart, driven, passionate... and under tight deadlines. And the nasty side effect of tight deadlines is that architecture drops by the wayside. Try to keep your architecture as clean as you can, no matter what the deadline. The extra time you spend now will pay itself back later when you need to maintain or extend that code. And other developers who have to work on it will thank you for it.
What's more, if you have a clean architecture, it'll fit in your brain better, and you'll spend less effort. What's better than that?
Simon Cooke is an occasional video game developer, ex-freelance journalist, screenwriter, film-maker, musician, and software engineer in Seattle, WA.
The views posted on this blog are his and his alone, and have no relation to anything he's working on, his employer, or anything else and are not an official statement of any kind by them (and barely even one by him most of the time).