Software Engineering Laws Everybody Loves to Ignore

For me, it's like 3 days later.

After about three 2 week sprints, my memory starts to rapidly decay about what I worked on or how I implemented something. It is a struggle for me, as my team is often called out by PMs about how certain functionality works under the hood and I have to retrace my steps.

> is this true for most people?

No, only poor engineers.

I noticed BTW the same for written text (code comments, wiki docs, blogs etc.) - when I re-read code comments I wrote a month later, I almost always find ambiguities, sometimes missing the larger point in the details etc.

Written stuff is hard as you have a lot of context in your head, your voice intonation etc.; sometimes a lacking comma, or reversed order of words, or a typo like missing an "s" or "ed" for plural/past can derail me for a good while while re-reading old text.

I believe that this observation is 100% true. And I agree that six months is optimistic. I'd say that if you wrote code three months ago and haven't looked at it since, then it might as well have been written by somebody else.

Well my favourite joke goes:

Starting code changes, notice some bad code, wonder who the hell wrote that crap, have to find that nasty person.

Fire up 'git blame', check code lines in question, "oh that was me, seems it is not that bad after all".

For me I usually forget the generic stuff. If I wrote something that was a bit different or if I put some extra effort or thought into it I find I can recall those implementation notes may be ever after a year.

I definitely don't feel that way.

I don't go into the code I wrote 6months ago knowing exactly what every line does, but I remember the broad strokes about what it is generally doing, where different logic will live, and it makes it much easier to jump back into code I wrote 6months ago vs code I've never seen before.

I've often worried about this but when I do go back to my old projects it's usually not that bad. Sometimes I'll find something dumb I did and rewrite it, but for the most part the code is easy enough to read and modify.

More than once I've thought I've run into a bug and figure out what the problem likely is, only to go into the code and discover that I already covered that case and the bug is something else entirely.

Most of the rewrites are because I had to do something awkwardly because some feature didn't exist in a library, or it was broken and I had to work around it. Then a couple of years down the road that bug or missing feature has been fixed and I can pull out the hacks and do it the elegant way.

For me it's about 4 hours

It's true but it can be mitigated with good comments and documentation and of course the most important thing, not writing over-complicated code. Sometimes the code you don't write matters most.

Code I came back to 8 years later felt genuinely alien. Otherwise I can come back to something 3 years old and remember the general architecture, but gritty details start fading after a few months.

I find this is especially if the code was written in haste, but if it's code I write professionally, it's usually easy enough to reacquaint myself. Probably the worst cases are the spaghetti code abominations that are generated by hackathons.

The more code you write, the more true it is.

Sometimes I go back to old code and go “What was I thinking”. Other days: “Wow, I was on it that day.” In any case, write like a stranger will be fixing your code later. Six months later, the stranger is you.

I could remember everything about every codebase I had ever written up until about the age of ~30. Now at the age of ~40, I can't remember what I wrote two weeks ago. It'll happen to you ;)

Surely it depends on many factors, like the size of the project, how many various parts of the codebase one is responsible for in their work, etc.

As far as rule of thumbs go, I think it's a good one.

> Genuinely curious, is this true for most people?

In my experience, understanding the code 6 months later isn't the challenge, but rather understanding why I made the set of decisions I did with regards to any tradeoffs I made when writing the code.

The best way I can think of to try and keep that from happening is to comment, comment, and comment some more. Specifically, I try to explain not just the HOW but the WHY of a certain approach that I took. The way I see it, if using a little more disk space for comments saves me a little time from having to try and remember why I did something 6 months later, I'm cool with that. :-)

Maybe early in my career?

In general, as I've adopted good conventions and know-how, I find code that I've written a few years ago quite readable.

I just opened some of my PHP code from July 2020 and started fine-tuning it.

It is understandable, not completely foreign, but a lot of the context around my previous decisions evaporated in the meantime.

>It goes on to say that even six months is optimistically high.

I'm in the habit of focusing my in-code documentation on why I made a choice, and my out-of-code documentation on code structure. This is probably counter intuitive to most people (who do the reverse from what I've seen).

The reason I do this is twofold. 1) Code structure changes don't occur that often for me (I'm a feature-terse programmer, only add what I need at the moment), and when it does change I really should be documenting that at the API level, not in the code.

2) The reason I made decisions are usually only relevant when I'm actually changing previous code (do to encapsulation and abstraction).

This method means that when I revisit an old project, I have my out-of-code API Documentation open in live-edit mode, using it for structure reference and adjusting it for any changes I make, and I have my reasoning sitting directly above the code I'm about to change. It works out really well!

Unfortunately, in school we were pushed towards documenting the structure in code, and using something like doxygen to extract that. I find that an ugly practice... The structure is always visible if you're adjusting code, but you're reasoning usually isn't.

I find good commit messages (and if you're using something like github, good pull request summaries) really helpful here for reminding me of the context around why I wrote the code.

You remember the ideas that made your system different (because you'll need those to sell) but you forget the ugly workarounds... my solution is to try and leave as few ugly patches and when I do put a comment!

Depends on the language for me. In Perl it takes about 6h.

If you want to ship code in that manner, why beat around the bush and pretend to be what you're not? Just do away with pull requests altogether.

There is such a thing as an “inverse Conway maneuver” where you do exactly that.

On the second question. Yes, you definitely should shape your org chart the way you want your architecture to be shaped.

At my large corp, we try to figure out and align stakeholders on the target tech architecture we want, and then sort the org structure out second as our way of mitigating the distortions that come with Conway's law.

More towards your question, having also been in a mildly successful startup, I think there is a certain amount of layering in your architecture that you can setup on day one (frontend vs backend), but so much success rests on execution and product fit and such that it's not worth wasting too many cycles overoptimizing the architecture if you aren't already opinionated on it. Go with the architecture that you can iterate rapidly with.

While I haven't been a solo dev, I'd ask myself the question "what work will I offload once I can afford to, and what architecture do I need to create so that next 1-3 persons able to work without a ton of my time?" Iterate from there.

I worked at a place where the org structure had been heavily influenced by software architects. And I found that there was way too much of a "this team will come in at this point to do this" kind of coordination assumed in the org design that may be possible with software, but works very poorly with actual people. People did not see the value in handing off or involving other groups just because the org plan said to, there were not proper accountabilities, and there was tons of communication overhead as groups flitted in and out of involvement and debated who had what responsibility.

Obviously you can't blame all that on software architecture, but it is a danger that comes with architecting an org in the same way as code, and expecting it to work once animated.

I've seen it work in reverse when the systems are just "too hard" to change. Think old legacy systems with large monolithic mainframe architectures as an example. Because it costs too much money to change them and the business needs to keep running many restructures just fail and managers just keep dropping.

I see Conway's law as an equals relationship IMHO, not a cause. The side that can give ends up adapting to the side that can't. In newer business where the architecture isn't established of course the structure influences the design. As the architecture matures and is worth a lot of money to replace it sometimes switches the other way. This of course can kill a lot of big corp's and IMO one of the biggest reason they may seem less agile to startup dev's - they have so many use cases to handle and systems have grown so complex it is a lot of effort to understand yet alone modernize these architectures. Often as well because they have been successful for awhile the regulators/governments have caught up with them and they have obligations that aren't so easily depreciated in any replacement.

Yes. Same with modular design in general.

"America's funniest home pages" should totally be a thing.

Try https://webcache.googleusercontent.com/search?q=cache:qI14xo...

pretty weird, haven't seen a .html document not load in ages

To be fair. The author warned us that every body loves to ignore them.

jwz seems to have a lot of hate in his heart, plenty to go around for everybody. He's a great developer, but it's rare for me to read anything he has written that doesn't come off as abrasive.

jwz says that explicitly in a lot of his writing.