8 ms·
Make it simple enough that a brand new completely green junior member of the team immediately understands it on first reading. This is why the software industr
by userbinator 5y ago
Make it simple enough that a brand new completely green junior member of the team immediately understands it on first reading.
This is why the software industry continues to decline: it's self-inflicted dumbing-down. I really don't understand where this rampant support for antiintellectualism comes from in the software industry, besides managers who want to make employees easily replaceable "cogs in the machine"; and dread what the world would look like if everyone was encouraged to do the same in other (natural) languages.
- jeffreygoesto 5y agoI don't think it is black and white. Disentangling a heavily optimized "clever" codebase took me four weeks once. Refactoring did not only make it more understandable but also faster. Seems like often "clever" is used with those quotes around it and really stand for "(accidentally) complicated". Edit: From the article: 'I’m drawn to this distinction because I feel like our discussions of “clever code” are too constrained.'
- kenver 5y agoThis made me think about how we use the term 'over engineered' in our industry. In most industries it seems to be a good thing (i.e. space shuttle). In our industry it's synonymous with bad, unnecessarily complex code. We seem to have a knack of taking positive attributes such as clever, and flipping them!
- dgb23 5y agoIt’s not exclusively used for clever code. I think a more common case for the term is to describe a program/system that covers way more ground than it needs to in terms of abstraction, tooling, features, scalability and performance. Example: I handed off a website a year ago that didn’t have any sort of remarkable engineering/usage requirements on the backend side. Internal operations of our client however insisted on deploying it on a kube cluster, so we had to accommodate for that. All they actually needed was maybe some caching, if at all. Mild case, but I think of these types of stories when thinking of “over engineering”.
- deleted 5y ago[deleted]
- eutectic 5y agoI would say that the space shuttle is the perfect example of the risks of over-engineering.
- AstralStorm 5y agoIt's not. Space shuttle was pretty well engineered to do the things it was meant to. (If anything, launcher and ops were underengineered hence the failures.) The problem was that it was meant to do too many things at the same time. Some of them were: being able to return to US territory from anywhere. (Hence semi-aerodynamic.) Carrying people and a lot of cargo. (Hence big.) Deploying any kind of cargo rather than defined operations. (Hence Canadaarm.) Being reusable. (but not the launcher...) Etc. The chief problem of it is that it was first in a class research vehicle. And you cannot refactor rockets. (At least not cheaply. Prove me wrong Starship.)
- kergonath 5y ago> In most industries it seems to be a good thing (i.e. space shuttle) It really isn’t the case in most industries. There are a couple of industries with inherent complexity and where the cost of failure justifies some kind of over-engineering (you could add particle accelerators, medical imagery devices, aircrafts, and things like that). In these cases, you throw a lot of money and very good engineers at the problem. Most industries are not willing to do that, because dit is expensive. So they produce unreliable crap that breaks all the time. In the vast majority of cases, over engineering means more parts that can fail in more “interesting” ways, and that are more difficult to diagnose because the thing is more complex than it needs to be. “Over-engineered” is really not a compliment applied to a car or a house, for example. Engineers are not gods. Sometimes they are stupid just like any other human. They also need to stay humble and recognise that a system needs to be as complex as needed to fulfil its purpose, but not more. > We seem to have a knack of taking positive attributes such as clever, and flipping them! “Clever” is a compliment. But you can have too much of a good thing, as in “too clever by half”. If you depend on something, you don’t want it to be clever, you want it to be reliable first.
- ehnto 5y agoIt's because the vast, vast majority of code is not and need not be groundbreaking computer science, it's boring business logic and glue code, and it's built in teams of regular people. We aren't trying to save the world with efficiency and cleverness, we are trying to be robust and understood. There is a time and a place for innovation of course, but you will be in a unique position when it happens. Perhaps you have a very interesting problem to solve, an opportunity to automate some part of the building, maybe you are architecting the system, or you are writing code for fun and not in a team. But you will know it when you see it, and if you can't tell then "write simply" is actually fantastic advice for you because you might be over-engineering some really boring stuff. It is genuinely good, pragmatic advice to execute most code as simply as possible because that is all it needs to be, and your code will probably be worked on by others in the team at some point and you are wasting their time if they have to pontificate about the meaning of life before understanding your code.
- unscaled 5y agoThis sounds like elitism in disguise to me. Sure, there are some cases when you want quick and dirty and just glue some system together, but most production code out there has some more important business requirement than "understandable by the cheapest engineers out there". For instance, if you're writing an account management system for a regional bank, you'll care most about the accuracy and longevity (including easy maintainability) of the system. If you're writing a microservice for a fancy web app with global distribution you might care about latency (high latency drives down CVR), reliability (errors drive down sales and ads too) and sustained agility (you need to develop features fast to keep ahead of competition). I think the second example covers most of what web and mobile developers do. I've definitely seen cases of over-engineered systems with many layers of leaky abstractions, but also many cases of under-engineered systems. Here are some well-documented maladies: 1. RYE (Repeat Yourself Everywhere) - You have the same business logic repeated in multiple places, because originally it didn't seem common enough or large enough to warrant DRYing up. This is obviously easier to read, since you don't need to dive deeper into more functions, but in practice the shared logic quickly diverges between the different cases, until it's very hard to specify what your system does. 2. "Let's just add an if branch here for this special case" - quick and dirty, as unclever as it can be, until you realize you need to deal with the combined permutations of 20 different branches. This is readable only in the very surface sense. 3. "Our junior engineers understand for loops better than map-filter-reduce chains, so let's use for loops instead of spending a few days teaching them": You can replace "for loops" with anything else that your junior engineers happen to know. The end result is not avoiding an over-engineered or "too clever" solution, but rather just avoiding a solution that is often simpler and easier to understand but just happens to be unfamiliar to your engineer. See also "blub paradox". 4. "This 500-line function is brain-dead simple and uses no fancy tricks". Likewise, it's easier for a junior engineer to write long-winded code and avoid thinking about even the simplest abstractions. And the code works! This doesn't make the code more maintainable or reliable though. 5. "Let's add ad-hoc retry with for loops and branches when necessary instead of creating an abstraction based on closures or let alone monads - this is just too clever". End result: reliability is added only after somebody complains about a certain functionality instead of being designed and baked into the service, and your service suffers accordingly. There are many more examples, but the general gist is that in almost every corner of our industry there are important concerns that require us to take our engineering practice seriously. I think statements like "It's all just glue code", "It's all just plumbing" or "It's just a CRUD app" are not constructive for quality. I wholly agree with you about simplifying things. I just think we should be mindful of the difference between "simple" and "easy" (as Rich Hickey famously put it[1]). What is easy for a junior developer to understand (because it doesn't contain any concept they haven't learned yet) may increase the absolute complexity. If you choose the "easy" solution here, you make the code seem _subjectively_ simpler to junior developers, at the price of _objectively_ (and measurably!) increasing cyclomatic, cognitive or state complexity. Unless the "clever solution" requires understanding that is beyond what we can expect the reasonable average engineer to learn quickly, I prefer to always err on the side of reducing absolute complexity, and code that is simpler to read _for senior engineers_. [1] https://www.infoq.com/presentations/Simple-Made-Easy/ https://www.infoq.com/presentations/Simple-Made-Easy/
- panta 5y agoThe OP didn’t advocate for dumbing down the project, it advocated for writing understandable code and avoiding “clever” code where possible. More often than not “clever” code is all about “local cleverness”, and it’s entirely avoidable. Interesting projects have inherent global complexity (in addition to some unavoidable local highly complex places), and there is no need to introduce unnecessary complexity by using smart tricks. In these cases you won’t go very far if the developers are replaceable cogs, you’ll still need senior intelligent, autonomous people.
- pwdisswordfish8 5y agoThey are the same picture.
- KaiserPro 5y ago> This is why the software industry continues to decline Nope, its bad communication. Imagine I quoted Feynman here, its a lot like clever code. If you can make it fast, but only if its unreadable, then you really don't understand the problem space. All of this attitude sounds very much like alchemist talk, rather than engineering. Real engineering (that is stuff that's physical like bridges etc) needs to be clearly designed and documented so that other people can build it. Software design feels a lot like a bunch of alchemists refusing to delegate, keeping the sacred knowledge close at hand, lest the apprentice steals it and starts up on their own. > the world would look like if everyone was encouraged to do the same in other (natural) languages. have you read james joyce? no, because its impenetrable "clever" English. Its an exercise in self absorbed intellectual masturbation. When ever people talk about it, they say how daring, how innovative it is, they never say its enjoyable, because its not. You can broadly say the same of The picture of Dorian Grey, its got some cracking one liners, but the rest of it is a mess. Compared to Joyce, its a marvel of concise clear English. Its still not overly readable. Clever code can be readable. However the vast majority of people that write clever code, don't intend it to be readable, they intend it to be a statement of their prowess.
- j_wtf_all_taken 5y ago> it's self-inflicted dumbing-down. I really don't understand where this rampant support for antiintellectualism comes from I don't think it is about dumbing-down or antiintellectualism. It is about knowledge. No matter how clever or smart you are, you do not know everything. So any special knowledge (about the OS, the language, etc) you have to be aware of to understand code is a barrier. I specifically don't mean domain knowledge. You got to know stuff about the problem you're trying to solve, sure. I mean knowledge about the tool you use to solve the problem. Its just a tool. Nothing else. A tool should be practical, the less you need to know to use it, the better. If you want to write a manual for a machine, you wouldn't use poetry, right? Of course some stuff is worth it. If there's a language construct that makes lots of things "better" (whatever that means) - cool, we should use that. But it should be some generic thing that can be applied to many problems (so its worth learning about it), not some specific thing that solves specific problems more clever.
- TeMPOraL 5y ago'unscaled gave a good example elsewhere in the thread[0]. "Our junior engineers understand for loops better than map-filter-reduce chains, so let's use for loops instead of spending a few days teaching them". This stuff really happens. Back in the day, in a company that just transitioned from Java 7 to Java 8 across its main projects, I've been told by the boss to maybe not use lambdas too much, because certain co-workers like John Doe[1] aren't so experienced and might not understand them. Thankfully, I was just starting another project with (initially) just a single "less experienced" dev, so I taught him these and related things quickly, and we proceeded to write simpler code, making full use of lambdas and stream APIs where appropriate. And aforementioned John Doe? Half a year later, he discovered on his own that Java 8 had lambdas, grokked them in like 2 hours, and went around the company, evangelizing their use for everyone. > I mean knowledge about the tool you use to solve the problem. Its just a tool. Nothing else. A tool should be practical, the less you need to know to use it, the better. A tool does not exist in isolation from the process. It's a part of it. Everywhere else than software industry, this seems to be understood. If you don't know how to operate the tools you work with, you're considered incompetent, not trained for the work you're performing. The solution to that isn't to dumb down tools - it's to train the operators. You have to pay a little bit up front to upskill your workers, and you then get to continuously reap the benefits of improved productivity due to better use of better tools. Should modern construction be done only with hand shovels, sticks and ropes, because junior construction workers will be confused by excavators and welders? That's how all this talk about junior-friendly code reads to me: an extreme case of being penny wise, pound foolish. Software development is a profession, the job of a junior is first and foremost to learn their trade[2]. -- [0] - https://news.ycombinator.com/item?id=27420543 https://news.ycombinator.com/item?id=27420543 [1] - Name intentionally omitted; the guy has been working in the company for many more years than I have - and was way better than our boss gave him credit for. [2] - Well, unless your company is structured around the idea that juniors do all the work, and seniors are "using their experience to multiply productivity of everyone" aka. just managers without the authority. Which is another trend in the industry that's worrying to me, because it pins the proficiency of the work to whatever junior hires learned before getting the job. And then we're surprised that tech debt is at all-times high everywhere.
- agumonkey 5y agoand potentially the dumbing down may increase the turn over rate which increases the need for dumbed-down code since everybody is a newb all the time