8 ms·
> Good code is code that can be understood by a junior engineer. Great code can be understood by a first year CS freshman. The best code is no code at all. Thi
by eqmvii 5y ago
> Good code is code that can be understood by a junior engineer. Great code can be understood by a first year CS freshman. The best code is no code at all.
This a thousand times. Having empathy for future devs, maintenance, and bug fixes is so important.
- runawaybottle 5y agoSomeone please translate that to Latin and start plastering that on office walls so people take it more seriously. It’s going to save all of our mental health in the long run.
- vlmutolo 5y agoIt's been seven years since I've tried writing any Latin, so you should assume this is butchered. (edit: I think it's less butchered now) codex bonus a discipulo prendatur codex magnus a novo prendatur codex optimus nullus est Part of the problem is I couldn't find any good word for "code". "Codex" sounds cool but may not be the best fit here. EDIT: Forgot a word. Also, I think "prendere" is better for "understood" here than "scire", which is more like "to know". EDIT2: My friend suggested using the subjunctive for "comprehend" so that it's "may be comprehended" instead of "is comprehended". Also I got the tense wrong initially and I think that's fixed now. EDIT3: "Ablative agents" are a thing. This is a rough language. Thanks, James. EDIT4: prendar -> prendatur; aka "oops, should have used third person"
- daenz 5y agoAmen. Something bizarre I have noticed though in junior-almost-senior engineers is that they pride themselves in obfuscating and writing "highly complex" logic, with no documentation. It's almost like they are demonstrating their new abilities in the worst way possible. I have been dealing with one of these engineers recently, and they have expressed to me that they love writing <highly problematic, confusing code> because it's so terse. It's been a point of friction, actually, because I have been trying to get other engineers to help on the software they have been contributing to, but it is nearly indecipherable without the original author's help. Very frustrating.
- runawaybottle 5y agoI wish more managers and business stakeholders investigated this more carefully. Team members of this type add a shadow overhead that impacts velocity dramatically. It’s always visible to average competent devs on the team, but can be invisible to managers who don’t investigate as to why only one person is particularly productive on the team. Most people won’t go to their bosses and say ‘so and so writes overly complicated code that’s making my life a living hell’. In fact, I think a third-party auditor would be a valuable service for dev teams to utilize at least once a year. Totally neutral party that can come in and say ‘We’re pretty sure the codebase is too complex and we noticed the commits came from so and so’. The business value here is you can root-cause velocity issues that can come from decent people who need to be reigned in (not necessarily fired). I’m literally prepared to pay to have these people objectively assessed.
- daenz 5y agoI would do this auditing job, no joke. A kind of "code-smell" service, that can yield problematic areas, along with a report of engineers that could use additional guidance/training/reigning-in would be super valuable from a manager's perspective. And because it's a neutral party, they can feel good that there's no politics. One challenging bit about this service would definitely be quantifying improvements. Since the problem is somewhat hidden by nature, you would almost need testimonials from other engineers on the team.
- swader999 5y agoI always say that's too hard for older devs like me to understand. Go easy on the elder abuse.
- kylestlb 5y agoFuture devs? More like future me... how can I build this so I can change it or fix it when PM decides against it in 2 weeks?
- phreack 5y agoAbsolutely, you need to care for that future dev who's an idiot when writing code today because that's going to be you in a week or two when you've forgotten all about it.
- austincheney 5y agoThat is frequently misinterpreted to mean use dependencies instead of writing code. It’s all the same to the product.
- whateveracct 5y agoThis sentiment is exactly why programming in an org-chart is so much different than programming as an individual. Don't apply corporate best practice designed to withstand turnover to personal programming - you're leaving abstraction and efficiency on the table. The better code for your own projects is almost definitely inscrutable to a newcomer a lot of the time. It's okay for there to be prerequisites to understanding.
- ritchiea 5y agoI agree with this in principle but in practice code I write that’s quick & easy and not very readable is usually not understandable by me in a few months either. So if it’s a personal project I hope to last I still want to keep it simple with my code.
- whateveracct 5y agoI'm not saying to hack away and make a mess necessarily. Sometimes the simplest solution also requires learning and building upon other concepts. Or sometimes, a simple interface is written around a complicated core. For example: The OP's quote is used time and time again to argue against FP concepts in industry - a newcomer doesn't know the first principles, so by the OP's folksy razor[1], that code isn't as good as less abstract code that doesn't require learning a new concept or two once and for all. [1] Folksy razors are the essence of every principle-ish-level engineer's methodology I've run into. Corporations value the ability to remove all human agency & decision-making from software development where possible.
- pbourke 5y ago> Corporations value the ability to remove all human agency & decision-making from software development where possible. Corporations value the ability to continue as an operating entity and make changes to the code after the proponent of Kleisli arrows and lenses has departed for greener pastures.
- 5y ago
- hkt 5y agoCame here to post exactly this quote. I've never seen a wiser drunk. So lucid, and so relatable.
- gigatexal 5y agoI came here to say this. +100 to this.
- MaxBarraclough 5y agoIt goes too far though. The virtue of simplicity needs to be balanced against the virtue of making proper use of advanced language features. A first-year student is unlikely to understand C++ template metaprogramming, or just about any Haskell code, but that's not to say they should always be avoided in production code. > The best code is no code at all This can be interpreted as advice to avoid the 'inner-platform effect' anti-pattern. Good advice, but personally I'd rather express it in terms of the inner-platform effect.
- mplanchard 5y agoIME good commenting alleviates a lot of the “problems” with using complex language features. I’m thinking redis style comments (see here[0] for antirez’s philosophy on the issue). If you’re doing something that’s not immediately obvious, explain what you’re doing! That way others can verify it during review, and when someone is reading the code later they can read the comment to understand what’s happening rather than having to parse the code. IMO this applies just as much to simple constructs as to complex ones. Big for loop? Throw a comment at the top telling me what it does so I don’t have to read it when I’m skimming later. Better yet use `map` with a well-named function. Either way, provide a semantically meaningful summary of what’s happening. [0]: http://antirez.com/news/124 http://antirez.com/news/124
- MaxBarraclough 5y ago> If you’re doing something that’s not immediately obvious, explain what you’re doing! Agreed. Comments have their place, and some code is unavoidably involved, just by the nature of unavoidable complexity. The solution isn't always to write simple code. If it were, we wouldn't bother studying clever and efficient algorithms. Also, it's important to ensure comments are updated when code is changed. I don't know who originally said it: Stale and inaccurate comments are no longer comments, they're lies. That blog post looks worth reading properly, I admit so far I've only skimmed it.
- craftinator 5y agoThe mantra I use with my team is "comment the details, document the strategy".
- taf2 5y agoThere is good or bad code - there is only code
- actinium226 5y agoI agree with having empathy for future devs, but I think it only goes so far. I've often seen junior engineers unable to differentiate between code they don't understand and bad code. Usually they end up thinking they can do a better job, decide to rewrite the thing from scratch, and take 10x longer to rewrite it than they thought it would take. And accomplish nothing in the end, because the thing they rewrote worked in the first place.
- MikeDelta 5y agoIndeed, and during rewriting they realize why the original code was made that way and how it solves the problem more efficiently than their rewrite.
- dataflow 5y agoI disagree strongly with it on multiple fronts. That concern should be secondary to your program actually doing its job well. Your customer will literally not care how elegant or ugly your code is; they just see the end result. And when the program fails them, it really doesn't matter to them whether your juniors understand the code or the error. Moreover, not every abstraction is (or can be expected to be) accessible to an entry level engineer. Some technologies just take a long time to master, and doing that can also require higher-level abstractions. So I would say great code is code that: 1. Does its job well (robustly, performantly, etc. in whatever proportion is applicable) 2. Is maintainable by engineers with reasonable expertise in the tooling in that order. If you can manage all that and make it accessible to your junior devs, that will of course make your code greater. But don't lose sight of what your customers care about. Your business isn't there to make you feel good about maintaining code, it's to provide customers with value.
- whateveracct 5y agoExactly. How many entry level engineers come onto a project per year? 5? Is onboarding them onto the project is a deliberate and streamlined way such an undue burden that you must change your programming style to avoid it?
- boojing 5y agoIt's not only about new hires. You will have to figure out things about code that you wrote 3/6/12 months ago.
- whateveracct 5y agoBut you can write code you can understand 12mo from now but have that same code be inscrutable to a new hire. Definitely different litmus tests.
- andy_ppp 5y agoThis assumes you are absolutely certain you know what the code should do. And that it does what you think it does. Hence while you might think “performs its task” is an easily defined I’d disagree. I’d take clear code that wasn’t working over code that was hard to reason about and somehow worked every day.
- jlos 5y agoAs a junior, the best I've seen is surfacing the complexity appropriately: 1) Readable Interfaces usable by juniors when parts of the code will be used by lots of devs and will almost certainly change 2) Higher complexity behind the interface for parts of the code that change less often and require more skilled engineers
- lanstin 5y agoAnd complexity needed to make a simple interface is the most forgivable complexity. Simple API, worth some cost to get there.
- rottc0dd 5y agoBut, I do not know if this metric is quite 'complete'. Because, I am very sure, wrapping concepts in mind is more difficult than understanding the code. I am not saying the code cannot be made better or more clear. But, it also depends on who you are writing to. Somebody who is not familiar with certain style of programming cannot easily read the code of certain level of complexity. When I was hacking away my first big program, I could not write functions. Or find reading functions easy. The whole thing was a big wall of glorified assembly sewn together by labels. I am not sure why I was like that then, but I found concepts 'functions' and recursion or any other conceptual stuff really hard. My code was, in its own twisted way, 'most simple' and utterly unreadable. I find the same sort of difficulties while reading some FP snippets. I confess it was a very short affair, but I had some difficulty reading it and even when I understood, I could not just write or think code in the same style. There are ways to make your code better, your intentions clear but 'can be understood by a first year CS freshman' is bit abstract criterion. It is kind of like, vocabulary and prose. You can make your prose clear. But, people have to work on the vocabulary on their own. > The best code is no code at all. This is completely agreeable. Edit : Changed some poor word choices. Added an analogy.
- BurningFrog 5y agoI think of it as writing code for the computer/compiler, rather than for human readers. If the computer "understands" the code, you think you're done. I real life working on a team with ever changing code, that is the barest rank minimum. As a young programmer, I thought I was a master when I got the code to work. Now I know that is just the start. Making it readable and changeable is where real mastery lies. This is very hard to convey to young fools as I used to be.
- jeffreygoesto 5y agoThere's even more. In the beginning you are proud if the code _works_. Later you find out it's 10x harder to write code that _can't fail_...
- SkyPuncher 5y agoI've been fighting this at my company lately. We have a CDF that _clearly_ rewards people who write really advanced Ruby code. We have a lot of working, but not perfectly architected code that people come back through, pull it out into a module, and add a bunch of "included" and meta-programming. It works. I look at their code and think "that's neat", but you added 0 functionality while making it hard for the lowest half of the engineers to work with. You could have accomplished the same thing with hard-reference to a class.
- chadcmulligan 5y agoThats what I've noticed with TDD advocates - the amount of code required is enormous and distracts from the flow of control. Everything replaced with mocks and stubs and there's objects replaced with instances from global scope, not very good.