I have a theory.

The smarter you are, the worse code you write.

When I was taking Computer Science classes in college in the early 2000's, I was told that the landscape of development tools was ever-changing, and rather than try to predict what cutting-edge technologies would still be relevant in four years, the curriculum designers focused on teaching general techniques for managing the complexity of a software project.

That phrase stuck with me "managing the complexity"

When I started my first full-time software engineering job, very dispiriting things would happen to me. I would submit a change for review, and then sit there and watch as the reviewer unfolded all manner of subtleties I had overlooked about how my change was going to break a bunch of shit. In the end, the reviewer wound up effectively writing a lot of my code, slowly, via a series of editions driven by objections in review.

At that point in time, I had already been making software more than half of my life. I was a newbie on a team with industry professionals, but still, my contribution to the code seemed disproportionately low. Engineers that had twice as many years of experience as me were dominating the code base, writing hundreds of times more lines. I wound up quitting with the feeling that I couldn't cut it.

Since then I've had other jobs, but stuff like that never seems to go away. Here's another example: sometimes I'll be implementing a feature by adapting some existing code that does part of what I need. Another engineer at the company will assure me that the existing code "works fine", so I think the process of adapting it to my purpose will be straight-forward. But when I commence... I discover a bunch of details making the task an unexpected slog. Again, the obstacles seem to be in the sea of caveats external to the code I'm editing.

Maybe when other people encounter things like this they dismiss it as simply part of the learning process. I tend to see it as a huge problem. And I used to think the problem was with me. I used to think I just didn't have the cognitive capacity to see all the details. To some extent this is certainly true; I've learned a lot since I started, and I've gotten better at thinking about code. But over the years, stuff like this continues to happen, and I've formed a new theory. I now understand that engineers who play an authoritative role on a project aren't necessarily better engineers. They don't write better code, they just know the codebase better. They seem like better engineers because you have to keep asking them how the code works. But that's actually an indication of why they suck as engineers because they wrote a bunch of code you can't comprehend.

I'm not saying all tech leads got where they are by luck, I'm sure they're really smart, too. But there's a problem with being really smart; the smarter you are, the worse code you write. You see, smarter people are better at managing the complexity of software mentally, and they don't need the code to be organized and readable.

Take function length for instance. There are two advantages to writing functions of a manageable size. The first is you can give those functions descriptive names, which makes the code more comprehensible. The second advantage is subtler. It's a well known fact that a great proportion of bugs arise from the programmer failing to realize all the states code can execute in. Code with shorter functions tends to be written in a more functional style which means less state, which means less bugs.

But the thing is: only stupid people need that. Smart people don't mind long functions because they can mentally manage all the possible variable states, nested control structures and crap.

As a stupid person, you'll probably get shut down if you try to factor a long function into shorter ones, because you'll probably break it. It is very difficult to reorganize code without changing the behavior in some way. Then some smart person will tell you to put it back the way it was because it "worked" before.

Fellow stupid people, we need to rise above that. It is possible to be smart and organized. Stand up for organization. If you made an organizational change and broke something, argue that the code was unmaintainable in the first place. I'm pulling for you. We're all in this together.