You’d think it would be common sense when writing something that other people will read. We don’t see people writing books in acronyms or omitting words.
How come so many people try to use code to show how smart they are?
How come so many people try to use code to show how smart they are?
My first CL at my first job out of college was writing a state machine at Google. I remember collapsing it into this dense, elegant representation by hinging on a couple of bits of state. It took me an extra half day, but I was really proud of the end result, and I remember being mildly put off by the request that I unroll it and make it explicit. Upon thinking about it for a bit, I decided it was entirely reasonable, and after a few more years at Google, I transformed into the kind of engineer insisting that every bit of code prioritize readability over everything else, in the absence of constraints like performance. Across the tech orgs and teams that I've run since, this has paid huge dividends. I'm writing a lot of tensorflow and C++ at a very fast-moving company working on a complex problem, and I don't know how anyone on my team would be productive at all without strictly prioritizing readability.
Being good at coding and having good engineering habits aren't the same skill, and the latter is about discipline and patience (and occasionally thinking like a dumber person), which are inherently less fun than unfettered technical challenges.
I’ve been thinking again lately about little bits I picked up via osmosis and my own early creative writing experiences. In fact I was just noting a couple weeks ago how refactoring resembles an exploratory writing exercise.
I think we need to embrace the creative writing similarities. Would we ever celebrate an author who published efficient, dense and cryptic text? Rarely.
One of the things we do want is someone who paints a clear picture in a few well chosen words. Another is to be inspired. Tricked or bored are not on that list.
We have ideas of a "grade 6 reading level", do we have such a scale for code? If not, why not?
Writing clever code doesn't mean it's being done for that reason. As the article notes, Guido himself agreed that in the early stages of developing a piece of software, such as in an early stage startup, it probably makes sense to write clever code, because you can get it done faster and therefore iterate faster on improving the code to meet user needs. At this stage very few people are working on the code (often just one), so communicating with other developers is not a big issue.
The need for making it maintainable comes later, when the product is mature and many more people are working on the code, so the need for clear communication becomes much stronger.
>We don’t see people writing books in acronyms or omitting words.
Math books written for mathematicians do this all the time.
I think it would be more accurate to say that we assume that other developers have the same amount of context about the problem as we do.
Going back and reading my own code from even a few months ago makes this very evident, as I frequently realize that I'd made various assumptions that required a much deeper level of understanding than I anticipated. The difficulty in providing a sufficient amount of context is readily apparent to me as I go back and fill in the gaps I unknowingly left.
And telling them their cleverness is hurting other people can be traumatic, for one or both parties.
I like being clever too. I’ve just sublimated that into more beneficial things like human factors.
I think that excuse falls over when you look at some old code you yourself wrote, and you find that you can't understand it.
That's presuming your smartness doesn't change much over time.
When I’m trying to add functionality of fix a bug, I’m going to read dozens and dozens of functions to winnow down to a handful of candidates.
Simple code can be filtered quickly and cheaply. Clever code requires contemplation. Which clears working memory.
Yes, I can understand your code. But I shouldn’t have to work for it.
If a critical service is experiencing growth and built on cryptic stuff, then the world may notice if no one can maintain it and it falls over.
when I write code for a concept i don't understand completely, it tends to be complex and cryptic. I'll go back to it after trying to understand the problem and the problem space more and be able to write simpler code.
When are you having fun reading someone else’s code? You’re usually there trying to solve a problem. Your plans for the day have gotten away from you. You may even be having a Bad Day. And this is at least doubly true for failing tests.
Take pity on the person.
An example that frequently occurrs is decomposing a large method into smaller methods. Okay, there are now more lines of code (due to adding method declarations), but what was really gained? The gain that can be had is identifying common use cases and factoring some of those methods out to utility classes that can be referenced from the same source file and others. This can be difficult to identify unless one learns to really look for these oppurtunities.
The approach I've been taking recently is presenting the idea as there's always a minimal level of abstraction, and code should try to achieve it. I'm interested to hear what others think about this.
Python not caring about the type of a parameter makes it easy to share code too.
It's tricky, isn't it? The original quote was about "clever code" versus "maintainable code", but they are not orthogonal: it's possible to write code that's more maintainable (because it's harder to use incorrectly) at the cost of being more clever (because you need to learn more of the language or standard library to understand it). One person's "more maintainable" is going to be another person's "too clever" — you're going to get a bunch of different opinions on where the line lies. Not everybody is trying to show off their brains.
I agree that code should be as straightforward as possible, but I don't think books follow that rule.