14 ms·

Good code is like a love letter to the next developer who will maintain it

317 points by feross 3y ago

mcdonje 3y ago
Most bad code doesn't exist because the writer didn't sufficiently love the future maintainers.
NetOpWibby 3y ago
Precisely why I also create READMEs in top-level directories. I'm not going to remember how to structure queries for my API a year from now. Future me will always appreciate how considerate present me was.
- imoverclocked 3y ago
  > Future me I like this term a lot more than "the next developer."
  - NetOpWibby 3y ago
    You know how on a plane the flight attendant tells you to make sure your oxygen mask is on before helping others (in case of emergency)? I think of coding well and documentation the same way. How can I help you without first helping myself?
  - chrisbuc 3y ago
    This is what I tell our junior devs. I remind them that the "next developer" may well be themselves in a year's time.
- persona_reuse 3y ago
  One can figure out 'how' and 'what' from the code, given enough time. The most valuable thing in code is the brain of the Past Person who wrote it, looming over your shoulder, telling you 'why' in very explicit terms. That 'why' also helps to show that Past You knew wtf you were doing, and lets Present You feel confident in making changes, because you know what the intent was. "I'll remember this!" is one of the greatest lies in CS.
  - quectophoton 3y ago
    Yeah when I find myself wanting to write a comment that describes the implementation, I usually end up writing a test where possible. I'm trying to think, but I can't come up with any kind of comment that has been useful that didn't have a "because" word, explicitly or implied. Like, even if there's a comment like: "This function only queries X and Y fields. Don't add more. If you need more than that, use this_other_function instead." It has an implied reason behind it, and the mistake is not adding that reason to the comment. So this comment would be missing something like "[...] because this is being used in a critical part of the code that is very nitpicky and it's very difficult to test because requires some annoying manual steps", or something like that. There are probably situations where a "what" or "how" comment really are better than "self-documenting code" though. I would probably appreciate those comments if I ever need to read branchless code, SIMD code, or similar performance-sensitve witchcraft.
    - a_e_k 3y ago
      > I would probably appreciate those comments if I ever need to read branchless code, SIMD code, or similar performance-sensitve witchcraft. I've done this before in production code. One of my only exceptions to my policy against leaving in commented-out code has been things liking leaving the unoptimized serial code commented out at the top of a section of some hand-vectorized code full of SIMD intrinsic. It clearly showed the intended "what", but was also useful to keep around as a baseline for performance testing and reference code to compare against for debugging.
Attummm 3y ago
And remember, the next maintainer could very well be you.
- SaintGhurka 3y ago
  Or it could be a homicidal maniac.
  - Gabriel_Martin 3y ago
    Or both, depending on how readable it is
- dasil003 3y ago
  Yeah, it's humbling enough when you are reviewing some old code and thinking "what idiot wrote this" only to git blame and realize it was you. What's even more jarring when you find some code, surprised the capability/feature even exists, then git blame and realize again it was you (this time hopefully with a pat on your own back because of how well it's written). Yes this has happened to me.
  - JohnFen 3y ago
    All of the code I wrote more than a year or two before the time I look at it strikes me as being embarrassing. I hope this is always true, because I think it says that I have grown as a programmer over that time.
  - roflyear 3y ago
    I recently had the opposite experience: encountered some code from 2017(!!!) that was really solid. Few "silly" things but the important stuff was there. I realized that when I did that project I "had the time to care" which is not the case lately!
  - LordDragonfang 3y ago
    Nothing beats the feeling of having a coworker suggest what might be a substantial change to a codebase you haven't touched in months, only for you to look at the code and realize that the way you wrote it makes it a one- or two-line change.
UnixSchizoid 3y ago
I write shitty code only I understand for job security. This is probably why I’m a sysadmin lol.
commandlinefan 3y ago
As much as bad code irritates me, I'm not quite so quick to blame the original maintainer - they may well have wanted, badly, to write something better, but been put under artificial (and usually meaningless) time pressure that didn't allow it.
- deleted 3y ago
  [deleted]
- Smoosh 3y ago
  I maintain mainframe systems and very often I would like to restructure code to improve it, but the requirement is to make the most minimal change that achieves the fix or change required. Mostly because the code is 30 years of patches and minimal changes which is not well documented and is extremely fragile and not well understood.
hirundo 3y ago
So a love letter to myself? Who wrote this crap?! `git blame` D'oh! Just today I found an old spec I wrote that was so completely mocked that the code it specified made no difference. I wasn't feeling the love.
manderson89 3y ago
Reminds me of the Damian Conway quote "Documentation is a love letter that you write to your future self"
- pwdisswordfishc 3y ago
  So documentation is only written by narcissists?
thebruce87m 3y ago
I guess I’m writing hatemail every day.
ThalesX 3y ago
Sorry next developer, I'm on a tight deadline, used to love this craft, now I just do what the product people tell me to get a nice paycheck.
- Arisaka1 3y ago
  Yep. Yesterday I ran into a job opening asking for "Java developer who delivers 3x faster than the other developers" in one of the bullet points. It's such a weird point to emphasize that you want speed with no concern to trade-offs, and the maintainability and scalability of the codebase will be the first victims sooner or later.
  - rpastuszak 3y ago
    Sounds like they're looking for a person who'll work 3x faster than the rest of the team by taking shortcuts and slowing everyone else down.
  - BugsJustFindMe 3y ago
    My personal experience is that the majority of developers I ever encounter at work (as opposed to within my social network) are usually slow because they're bad engineers who don't understand problems quickly, don't have the knowledge or experience to see solutions quickly, and in general don't think deeply quickly. It's not hard to 3x performance without sacrifices when the baseline is mediocre at best. "Fast must be cutting corners and not just actually better at programming" is a weird fallacy to hang your hat on.
    - 3-cheese-sundae 3y ago
      There is always a cost to everything.
      - BugsJustFindMe 3y ago
        > There is always a cost to everything. There's a huge cost to having engineers who are bad at understanding and solving problems. The cost of having people who are good at understanding and solving problems is supposed to be that you pay them more, but that's not how employment incentive structures work in practice because information asymmetry and stigma around talking about salaries.
beebmam 3y ago
In my opinion, good code is like a Brita filter. It does its job, will one day need to be replaced, and it should be easy to replace. More importantly: metaphors are not a healthy way to understand an idea. Ideas are more nuanced than a metaphor could possibly account for. Abstaining from metaphors might not make for a catchy headline though.
- xupybd 3y ago
  In my opinion, metaphors are like a picture. They can communicate vast amounts of information very quickly but can have inaccuracies. You should expect some additional nuance when receiving a metaphor.
- dmbche 3y ago
  Little pushback here - metaphors are great tool to understand something, and can convey some meaning more efficiently than other means. But "the map is not the territory"!
  - themodelplumber 3y ago
    The territory isn't the territory either, so no big deal!
- Minor49er 3y ago
  Metaphors are also ways of communicating ideas. A good metaphor is as simple or as complicated as it needs to be in illustrating a new concept
  - KarlKode 3y ago
    Problems arise as soon as you (ab)use a metaphor (used to explain a higher level/adjacent problem) to explain concepts it was never meant to model. Example: Array of items as a shopping cart: how do you efficiently remove an item from the array (as you can from a shopping cart)?
    - deleted 3y ago
aye01 3y ago
fuck the guy after me. I write good code for my own sanity and so my OCD doesn't make me want to refactor it all later. it's like saying save the trees for your grandchildren or the future generations. fuck them, I want a clean environment for myself gosh darn it!!
- NetOpWibby 3y ago
  Had me in the first half
nashashmi 3y ago
The next developer ruins your code like new twitter runs old twitter or new arrogant engineer overwrites old humble engineering.
rpastuszak 3y ago
1) "Code sober, debug drunk" It's harder to read the code than to write it so if you can barely comprehend the thing you just wrote, you probably won't understand it in the future: https://sonnet.io/posts/code-sober-debug-drunk/ https://sonnet.io/posts/code-sober-debug-drunk/ 2) I think it's more like speaking with ghosts (including a spoiler for The Sixth Sense): https://sonnet.io/posts/emotive-conjugation/ https://sonnet.io/posts/emotive-conjugation/
- majikandy 3y ago
  >it’s harder to read code that to write it Isn’t this only true of bad code? Good code is almost certainly the other way round, harder to write than read… just like a really good book was much harder for the author than it was for you, the reader.
  - ezekiel68 3y ago
    Code isn't a book. The quote you call into question is semi-famous and I believe the idea is that it's relatively difficult to jump into one code unit of a larger system and get back up-to-speed because one must fill the data cache of their brain with all the considerations for why the author may have done things in a certain way. The algorithm choices and edge cases and exceptional logic paths were clearer to the one writing the original at the time.
  - rpastuszak 3y ago
    I agree with the sibling comment. > just like a really good book was much harder for the author than it was for you, the reader. Now, I suppose this could work for a nested narrative novel, where the reader is meant not to just read the book, but to rewrite and expand it as they're reading it. Adding new ideas, new sub stories on the way. Think 100 Years of Solitude blended with Italo Calvino's Invisible Cities. Seems like the [*]Bible is a good literary example of an async collaboration similar to code: notoriously hard to interpret, and full of dubious historical information and contradictions. I know that Christians call it the "good book", but most of them don't use the word "good" in the same way they'd use it to describe a Nabokov or Eco novel. [*] or most ancient religious texts, like Avesta
ModernMech 3y ago
Plot twist: that next developer is you. Love yourself!
malikNF 3y ago
I prefer the quote that goes "Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live."
- majikandy 3y ago
  This. I was about to mention the same quote. This quote alone has served me well over the years. Sounds jokey but if you live by this, it’s brilliant.
mellosouls 3y ago
This blog entry is a much nicer and more graceful version of the old adage about writing your code like the next guy is a psychopath who knows where you live...
more_corn 3y ago
Good infrastructure is too. I had a colleague deploy the power whip for the last available rack position on his way out the door. Years later when I desperately needed that rack to keep the site up I was able to roll it in and light it up without waiting 6weeks for an electrician change request. He saved my bacon by thinking ahead. It was a gift he gave me, never mentioned and was not around to receive thanks for. I aspire to be more like him in everything I do.
hkon 3y ago
Good code is not like art, such as good books or paintings. No matter the quality of your code, if the product or service is not a good market fit. It will be retired. No one will stumble upon it or pick it up after it's gone. Knowing this, the only reason for putting effort into it is to make it easier for myself.
- majikandy 3y ago
  The two aren’t always mutually exclusive, you might be writing code for a good market fit that stands the test of time and needs maintaining. The times you appreciate it are actually when you open something and it’s nice and easy to change and you realise you were the one who wrote it. But real developer happiness comes when you have the same experience and someone else wrote it.
  - hkon 3y ago
    Indeed, I'm just trying to highlight your efforts as an 'artist' might be wasted. I recently worked on a project with some seriously clean code. My job? Shut it down. This made me sad.
- mostlylurks 3y ago
  > No matter the quality of your code, if the product or service is not a good market fit. It will be retired. No one will stumble upon it or pick it up after it's gone. This applies to artistic endevours like books and paintings as well (especially those two, since markets for them are very oversaturated). Your technique might be masterful, but if your art doesn't align with current trends (along with a number of other factors), it'll drown in the endless barrage of other art, and nobody will stumble upon it or pick it up, even if it's still available.
  - hkon 3y ago
    Yes I thought about that, I was thinking in the sense that someone in the future might actually stumble upon a painting or a book. They won't with proprietary forgotten code.
xupybd 3y ago
> The beauty of our creations, however, is not judged solely by the elegance of our algorithms or the efficiency of our code, but by the joy and ease with which others can build upon our work. Often this is not true. Our creations are judged by the user. They don't care how good it is under the hood. They care that it works correctly, that it's easy to use and that it's as fast as they need it to be. Your boss should care that it's well written because that should mean it's cheaper to maintain. But, they don't look that far into the future when evaluating your performance. So, often they only care about how fast you did it and how happy the customer is with it. Our industries incentives don't often align with good code.
deleted 3y ago
[deleted]
swayvil 3y ago
The computer in this metaphor is what, a marital aid?
henning 3y ago
dear future developer, nothing matters and code will still be hard to read even if I try my very hardest to make it as good as i can. the world is dying and we are doing our best to kill it. you having a hard time understanding my code is not really anything that can be fixed. it pales in comparison with the actual problems the world faces. tough it out or rewrite it. sorry
ugh123 3y ago
Meh. I've seen teams and projects bogged down by "good clean code" rules and nit picking code reviewers. These folks, typically "staff" engineers, over-police the repos and care more about clean code than delivery and execution. I'm waiting for the day where AI/co-pilots can enforce team and industry best-practices, style, maintainability, testability, etc before the code is even committed. Call it "uber-linting" and get rid of code reviews.
- Rietty 3y ago
  Can't you already do that with pre-commit hooks? We use those at work to check a lot of stuff like that before a commit ever goes through.
  - ugh123 3y ago
    Of course! I'm talking about the kinds of checks and scans that are made on the code during the pre-commit hook
- crucialfelix 3y ago
  I'm working with someone who asks me to remove documentation that summarizes what a function does. (The whole codebase is stripped bare of documentation.) Copilot can write implementations based on comments. Soon I think it could flag potential errors if code doesn't do what the comment claims it does. Then we can do that in code checks.
  - randomNumber7 3y ago
    This mentality drives me crazy. I mean i agree that most comments are bad, but some high level description what a function/object/library does or how it is supposed to be used is something different. When it misses then I have to read the ** code to use the ** thing. And I am not interesed in that at all. Maybe they do this so someone has to read their "good" code.
m00x 3y ago
After more than a decade of development, I've come up with this mindset: I don't really care that much about the developer, and care a lot more about the users of my product, especially since that developer is usually me. If I'm unsure of the value I'm adding, or if the ability to do something is greater than its quality, I will take shortcuts if needed. If the codepath is critical, or if doing so is dangerous, I will take my time on the quality and the foolproofness. I will be pertinacious in this mindset, and if managers try to rush me, I will remind them of the consequences of failure and log everything. I've seen too many developers (myself included) spending weeks and months on perfecting something that's never used, or barely used. The latter issue of not spending enough time is a lot more rare, but does happen.
anon7331 3y ago
It's a very nice way to imagine good code. More likely, someone inexperienced or less caring will come along and edit it just enough to turn it into mediocre code and no one will care anymore.
loph 3y ago
Truth. Years ago a wise man told me "The compiler is not your customer. The next person who maintains this code is your customer. It might be you."
- m00x 3y ago
  The customer is the one using your product, not the one maintaining your code.
  - ezekiel68 3y ago
    A common reply, but misguided. A corporate coder who is not also CMO and CEO does not produce products for the end user. They produce code units which, after build, deploy, and integration, become useful building blocks in an overall solution which may (the company hopes) be a product for the end user. From this standpoint, the code they write will often be 'consumed' by other coders and by future themselves. The consumers are therefore coders.
    - m00x 3y ago
      Sure, but usually you develop an interface to your service/code, and they shouldn't have to know the internals. If they have to look at your code to figure out how to use it, you've already lost. Hence the code isn't the product, it's the means.
imoverclocked 3y ago
As someone who has gone back and read my old code as well as a lot of others old code, there is no such thing as good code. IMHO, the problem is one of cultural context which is often not shared between generations of coders. Languages and best practices can change so violently that best-practices one decade are often anti-patterns in the next. As a codebase outlives its best-practices, do you stick with them and extend with those same anti-patterns or do you implement new things with a different mindset than the rest of the code? -- If you break with tradition then you are making it harder to understand the codebase as a whole. eg: why do we have a mix of procedural/OO/functional/... methodologies with spaghetti code at the core? -- If you refactor everything then you are definitely breaking something. eg: you have a 10M+ line java codebase with transformations bringing you into the 2020s from coders who originally knew C and Java 1.4. -- If you keep with tradition then are you writing the best code possible? eg: would you willingly use goto of some variant in new code if you jumped into a Cobol 74 codebase? I think what the article really wants to talk about is "clear" code or "understandable" code and not "good" code.
- woooooo 3y ago
  Style changes over time, but factoring is evergreen. Something could be written using Java 1.4 idioms with good organization and factoring, or using the latest functional hoohas with everything all mashed together. Or the inverse, of course. If the structure of the code matches the structure of the problem, the implementation style is a much smaller deal.
- 38 3y ago
  > there is no such thing as good code definitely not true. this is good code: https://github.com/torvalds/linux/blob/master/fs/file.c https://github.com/torvalds/linux/blob/master/fs/file.c this is good code: https://github.com/golang/go/blob/master/src/strconv/atoc.go https://github.com/golang/go/blob/master/src/strconv/atoc.go its formatted, commented, direct. the fact that you struggle with writing time tested code does not mean that everyone does.
  - grepfru_it 3y ago
renox 3y ago
The emphasis on tests made me laugh: I work on a project where it's mandated that all the code is covered by Unit Tests. In my estimate the time to make UT is 3* the time to create the code. And no, nobody use TDD in this project because it takes 3 minutes to compile one UT (C++ sigh), so we all do 'post coding' tests. While sometimes the UTs do help, they're also a huge burden: wants to fix some code? Well you also have to update the UTs..
- bcoughlan 3y ago
  Overly granular tests are a scourge of our industry, unless you’re writing a widely used utility library. It leads to tests that become a useless burden for even mild refactoring. Writing larger test cases that test the actual functionality is a game changer. With Testcontainers and good mocking tools you can spin up a real version of your app with external dependencies mocked and faked, and write test cases against the same input layer your user uses. If your test fails you can be pretty sure it’s because you broke something. This is a layer between unit and integration tests that you don’t read much about. I call them “service tests” (coming from a microservices world). Investment is still needed though to reduce the effort of implementing tests, like extracting common fixture code so that every test doesn’t need long winded setup code. Also snapshot testing libraries take the pain out of writing assertions. I am speaking from the API based backend world so YMMV. Once you’ve worked this way it’s hard to go back. Any developer can come in and confidently make changes. You spend way less time investigating regressions and broken environments, so you can release more frequently (which takes a whole other layer of pressure off the team)
ubermonkey 3y ago
I've always said "write good, well-commented code as a favor to whatever poor bastard has to work on this in three years, and realize that the poor bastard in question may well be Future You."
deleted 3y ago
[deleted]
yash8141 3y ago
lol use this analogy for surgeons. Every heart bypass is love letter to other surgeon.
laserDinosaur 3y ago
An article on HN a while ago posited that 'bad code' is directly correlated to forgetting what the code does over time - not the code quality itself. When you green-field a project, everything is fresh in your memory and the code feels great. When you come back to the exact same code a year later you you've lost your landmarks, there's workarounds you don't remember why they exist, suddenly you hate it, ugh this code is terrible! So you re-write it, making you more familiar with the code again and making it easy to remember - suddenly its good code! I try to keep that in mind when writing my code. Sometimes its comments, sometimes its documentation, sometimes its CleanCode™, sometimes its big blocks of text explaining why the heck a certain class exists, but my approach is "Write it for myself in a year when I can't remember what the hell half this stuff does", using every tool at my disposal to achieve that.
henry_bone 3y ago
"At the start of my book, Learning JavaScript Design Patterns, I say "good code is like a love letter to the next developer who will maintain it". It is an intimate correspondence, from one developer to another, spanning time and space." Seriously?! It's simple. It's a matter of respect, and treating others as you would like to be treated. It's no fun trying to figure out the "why?" of some code you've inherited responsibility for. It can be frustrating and time consuming. So why would you put others through it. Make the code and the reasoning behind it as clear to the next dev as possible. Explain it with comments. Refer to issue links. Make it so that there's minimal - preferably zero - unnecessary digging for the next poor soul who'll work on it.
- midoridensha 3y ago
  >So why would you put others through it. Because I've found there's a bunch of developers who apparently think it is fun to figure out the "why?", and they code accordingly. >So why would you put others through it. Because they think their code is "self documenting" and perfect and that anyone that can't immediately understand their code is too dumb to be working with it. >Explain it with comments. We just had a discussion here in the last week or two where people were actually saying that comments are completely useless and should never be used. >Make it so that there's minimal - preferably zero - unnecessary digging for the next poor soul who'll work on it. Sounds great to me, but in my experience it's a minority of developers who agree with you. It makes working on others' codebases very frustrating in most cases.
osigurdson 3y ago
Or yourself, years later after you have forgotten about it.
drbojingle 3y ago
Unless they look at it and say "there's no abstractions anywhere. Why did they use 'THAT' lib? Full rewrite needed. Hate this code in paticular." Good code is contextual and subjective.
pohl 3y ago
So my side project is like Narcissus having a wank, then.
yodsanklai 3y ago
Developers love to debate about these things, but everything has been said already. I've noticed that the better the developers, the less they engage about these topics.
- 000ooo000 3y ago
  Developers who enjoy discussing what makes code good are worse developers than those who don't enjoy discussing it? Is that the thrust of your comment?
- ezekiel68 3y ago
  > but everything has been said already. It turns out this is true for well over 90% of relevant topics on the planet. Every year in the US, over 4 million people turn 18 years old and over 3 million people of various ages die. If we contract this dynamic to people who enter and leave our industry, it becomes clearer why it is not only helpful to say what has been said already, it is vital. The above has already been said also.
throwawaaarrgh 3y ago
Code is communication about as much as a septic line is communication to the next plumber or homeowner. It's a part someone will have to maintain after you. But it's also just a septic line.
mattgreenrocks 3y ago
After almost 20 years of writing the best code I can muster as much as I can, I’ve come to understand that most people won’t ever really appreciate it for the effort you put in. Many won’t even notice; they’re too preoccupied with their own lives to open their eyes to what is there. Nor do they give a damn about mastery. But, that doesn’t mean it’s a waste. I don’t think I’d do much differently in retrospect, except be far more cautious about where and who I spend time around. Even this very thread has some pretty bad vibes: “who can say what good code is?” “good code can’t exist with deadlines.” I feel really bad for junior/intermediate devs that read this stuff and internalize it.
- Gigachad 3y ago
  Usually the situation is someone has meticulously crafted some perfect system which can be extended and reused in many coherent ways. And then that person leaves the company and no one else truly understands how it works or was meant to be used so it gets a series of hacks and patches applied to it which violate the original design which is known by no one at the company. For most projects this is not that big of a deal, the component gradually becomes less coherent and the original requirements change so much that one day someone will decide that the whole thing will be rewritten from scratch.
  - thumbuddy 3y ago
    And this is why Go lang exists... The trade off is screw brilliant engineering just make it simple so other people can build on it easily. Not saying it's my favorite, but it has it's merits long term.
    - AdieuToLogic 3y ago
      A semantically weak language does not reduce the inherent complexity of a system, as problem complexity is constant. What Go does is encode solution complexity implicitly throughout a code base. This is the same effect JavaScript often has.
      - 3y ago
miki_tyler 3y ago
FTFY: Good code is a love letter to your future self.
8note 3y ago
Something I'd consider for the good code is leaving open nice easy tasks for future developers to pick up so they can get a sense of how the codebase works. Just reading isn't as good as interacting with it
JonChesterfield 3y ago
Sometimes I go to change code to do a new thing and it is easy to do. The new cases fit in, the existing system doesn't explode, all is good. Sometimes the code is beautifully factored and tested. Maybe even documented. It then proceeds to fight against the new change. Maybe the type invariants fail everywhere for reasons that price spurious. Maybe code far away makes dubious assumptions and breaks in response. In the worst case, it's beautiful nonsense held up by undefined behaviour and the language has come to collect the tax. I like code that can be changed to do new stuff without everything around it exploding. That's probably what I'd call good code. It's in the context of tolerating future requirements well as the future is now. I do not see such code often.
renegade-otter 3y ago
Write good code. Professional code. Simpler and easier to understand code. That’s it… Some Leetcode jock will come in one day and rewrite it anyway, or a new CTO will crash the joint holding a bathroom sink and make your code an orphan. Or the company will just disappear. The code that i write like my own is, well, my own. Because that’s the code I come back to years later and I maintain, and always will. Everything else is ephemeral.
ww520 3y ago
I largely follow the forgetful programming practice, i.e. I will get it out of my mind after finishing it. This forces the code to be clear and consistent so that I can pick up on it easily if I need to look at it again.
tmaly 3y ago
If the headline is the case, then I have been in some bad relationships.
whoknowsidont 3y ago
The only good code is no code. All lines of code will decay, teams will move on, assumptions will change, refactoring efforts will be non-exhaustive, dominant skill sets and experience in the industry will shift. This is fairly tired conversation and while superficially interesting, there is simply no way to define good code except through local consensus of the people writing and reading the code. But that's as far as it will go, and time will will take what's owed to it.
AdieuToLogic 3y ago
While I would not categorize good code as being "a love letter", I would say that it behooves software engineers to remember that the solution they encode is read many more times than it is altered. Like, 1000x more.
humility 3y ago
'Good documentation is a love letter you write to your future self' vibes anyone?
patrulek 3y ago
What a shame im not romantic at all.
k_bx 3y ago
So writing good code is gay?
p0w3n3d 3y ago
Very often writing good code is a love letter to your future-self. So many times I blamed the git repo to check who was so stupid to write such code, and it was me...
quectophoton 3y ago
> Good code also adheres to established best practices, [...] Controversial opinion, but in my experience so far people usually say "this is best practice" as a way to avoid thinking, or to masquerade personal preferences. Not always, but more often than not. As soon as you ask "why is it a best practice?", "what are the consequences of not following this best practice?", "since 'best' implies there's a 'not-best', what is an example of the 'not-best practice' that this wants us to avoid doing?". The answer is usually something vague and handwavy like "because it's more scalable", but if you challenge that by saying "what do you mean with 'scalable'? can you give an example?", you usually won't get an answer. Doing stuff without understanding the reason, that's cargo cult. To be clear, I have nothing against people saying "I understand the code better like this"; it's subjective but honest, and it doesn't try to pass a subjective argument as if it were an objective truth. What I dislike is people saying "this is best practice" like an absolute truth that must be blindly followed and never challenged, without even considering the circumstances of the current project. Please spare me from turning a simple HTTP CRUD of 4 endpoints into an overkill Icosahedronal Architecture with a reason like "when we need to write an v2 this will make it easier without needing a rewrite!"; because I know that when the time comes for an v2 you'll rewrite from scratch anyway because then you'll want to use the new and better(tm) Perpendicular Riemann Zeta Architecture.
- utresk 3y ago
  I understand the spirit of your comment here, but in my area of experience, security, there are certainly objective “best practices”. There is almost always pushback on security considerations, and partly because those methods quite often change and improve with time. The term then becomes a blanket phrase that captures the constantly evolving landscape and necessity of accepting those new changes. You’re right that it is becoming over used. Like most abridged language, once your favorite becomes popular a new way to express the same underlying idea usually comes along.
  - quectophoton 3y ago
    Oh yeah, no doubt there. If a nobody like me writes a random blog post saying my custom way of doing ThisSecuritySensitiveThing is the best, at the next microsecond I'll have half the world linking me to like 20 different papers and 5 real incidents proving why I'm wrong. And I wouldn't be able to wiggle my way out of that criticism with responses like "but it works for us".
pictur 3y ago
I don't think being so romantic helps much. To take these articles seriously is to believe that there is such a thing as good code. but I don't think there is a good code that will make everyone happy. I understand the effort it takes to make the code something permanent, but I think the code has to be something that has changeable and the processes have to adapt.
misja111 3y ago
Here are my 2 cents, after 25 years of development in several companies. If you want to do the next developer a favor, your codebase should be simple to understand. Period, that's it. Simple to understand means: 1. Don't use fancy design patterns, FP constructs, performance optimizations etc. Unless the use case specifically requires it. 2. Code should do whatever it needs to do to fulfill its business requirements. Nothing less and preferably also nothing more. 3. Readable code beats documentation: only document the 'why', and only when it is non obvious. If you find you're documenting the 'how', have a second look if you can write your code in such a way that it explains itself. 4. Explain how to build the project, run tests and whatever else is non obvious in a Readme file in your project. Documentation anywhere else, such as on Confluence, will not be maintained or read.
- The_Colonel 3y ago
  Where "fancy" is relative. There was a time when Java 8 streams were fancy for many devs, today it's the default way to manipulate collections. I think the code should be "optimized" for the expected audience (of other devs). If you're a single rock star in a mediocre dev shop, you need to code differently than when you're part of a team of MIT PhDs.
  - kaba0 3y ago
    That’s actually a very good point!
haspok 3y ago
> (...) and the practice of Test-Driven Development (TDD) are indicators of a carefully crafted 'love letter'. I call BS on this one. TDD is usually a sign of a struggling junior and results in the worst code quality possible. Also, the next developer is in many cases myself, months later, trying to fix something or adding a new feature. I wouldn't care about other developers, because everyone has their own style and niggles, it is enough to cater to my own niggles, can't be bothered about others. And I also don't make a fuss about code written by others, as long as it meets some minimal standards.
dingi 3y ago
There might be love letters like that but any codebase that has been around for couple of years is not that. I'm yet to see any codebase in the industry that I can describe as a Love letter. I'm starting feel like I'll never find such a thing. Just make do with what you have. They are not paying you for reading love letters. It's mostly for maintaining and putting band aids over shitty code bases.
jeffrallen 3y ago
Sometimes it's not a love letter, sometimes it is a note saying "yeah, I don't like this anymore than you do, let's just get this over with so we can go take a coffee break and come back to something more interesting". Code works. Not all work is fun and beautiful, some work is not even worth doing. But making something work because it needs to work is also worth doing.
SleepyMyroslav 3y ago
I have come to conclusion that there are different types of people who work with code. There are writers. They can not stop writing. If something tries to stop them they move on and keep writing. Most of the code around is written by very small amount of people. Personally I came to terms with myself for not having to do that. Some companies who rush things to market do not understand it but it is okay with me. Looking back at years and shipped projects I do not trust such metaphors as in the article. I prefer other pov. Where I grew up one songwriter and performer coined it (sorry at incorrect translation) "[they] write as they breathe. It is a natural order of things". So if I do not like working with someone's code I have to move on.
justincredible 3y ago
[dead]
drderidder 3y ago
Including your future self.

317 points by feross 3y ago

Most bad code doesn't exist because the writer didn't sufficiently love the future maintainers.

Precisely why I also create READMEs in top-level directories. I'm not going to remember how to structure queries for my API a year from now. Future me will always appreciate how considerate present me was.

imoverclocked 3y ago
> Future me I like this term a lot more than "the next developer."
- NetOpWibby 3y ago
  You know how on a plane the flight attendant tells you to make sure your oxygen mask is on before helping others (in case of emergency)? I think of coding well and documentation the same way. How can I help you without first helping myself?
- chrisbuc 3y ago
  This is what I tell our junior devs. I remind them that the "next developer" may well be themselves in a year's time.
persona_reuse 3y ago
One can figure out 'how' and 'what' from the code, given enough time. The most valuable thing in code is the brain of the Past Person who wrote it, looming over your shoulder, telling you 'why' in very explicit terms. That 'why' also helps to show that Past You knew wtf you were doing, and lets Present You feel confident in making changes, because you know what the intent was. "I'll remember this!" is one of the greatest lies in CS.
- quectophoton 3y ago
  Yeah when I find myself wanting to write a comment that describes the implementation, I usually end up writing a test where possible. I'm trying to think, but I can't come up with any kind of comment that has been useful that didn't have a "because" word, explicitly or implied. Like, even if there's a comment like: "This function only queries X and Y fields. Don't add more. If you need more than that, use this_other_function instead." It has an implied reason behind it, and the mistake is not adding that reason to the comment. So this comment would be missing something like "[...] because this is being used in a critical part of the code that is very nitpicky and it's very difficult to test because requires some annoying manual steps", or something like that. There are probably situations where a "what" or "how" comment really are better than "self-documenting code" though. I would probably appreciate those comments if I ever need to read branchless code, SIMD code, or similar performance-sensitve witchcraft.
  - a_e_k 3y ago
    > I would probably appreciate those comments if I ever need to read branchless code, SIMD code, or similar performance-sensitve witchcraft. I've done this before in production code. One of my only exceptions to my policy against leaving in commented-out code has been things liking leaving the unoptimized serial code commented out at the top of a section of some hand-vectorized code full of SIMD intrinsic. It clearly showed the intended "what", but was also useful to keep around as a baseline for performance testing and reference code to compare against for debugging.

Attummm 3y ago

And remember, the next maintainer could very well be you.

SaintGhurka 3y ago
Or it could be a homicidal maniac.
- Gabriel_Martin 3y ago
  Or both, depending on how readable it is
dasil003 3y ago
Yeah, it's humbling enough when you are reviewing some old code and thinking "what idiot wrote this" only to git blame and realize it was you. What's even more jarring when you find some code, surprised the capability/feature even exists, then git blame and realize again it was you (this time hopefully with a pat on your own back because of how well it's written). Yes this has happened to me.
- JohnFen 3y ago
  All of the code I wrote more than a year or two before the time I look at it strikes me as being embarrassing. I hope this is always true, because I think it says that I have grown as a programmer over that time.
- roflyear 3y ago
  I recently had the opposite experience: encountered some code from 2017(!!!) that was really solid. Few "silly" things but the important stuff was there. I realized that when I did that project I "had the time to care" which is not the case lately!
- LordDragonfang 3y ago
  Nothing beats the feeling of having a coworker suggest what might be a substantial change to a codebase you haven't touched in months, only for you to look at the code and realize that the way you wrote it makes it a one- or two-line change.

UnixSchizoid 3y ago

I write shitty code only I understand for job security. This is probably why I’m a sysadmin lol.

commandlinefan 3y ago

As much as bad code irritates me, I'm not quite so quick to blame the original maintainer - they may well have wanted, badly, to write something better, but been put under artificial (and usually meaningless) time pressure that didn't allow it.

deleted 3y ago
[deleted]
Smoosh 3y ago
I maintain mainframe systems and very often I would like to restructure code to improve it, but the requirement is to make the most minimal change that achieves the fix or change required. Mostly because the code is 30 years of patches and minimal changes which is not well documented and is extremely fragile and not well understood.

hirundo 3y ago

So a love letter to myself? Who wrote this crap?! `git blame` D'oh! Just today I found an old spec I wrote that was so completely mocked that the code it specified made no difference. I wasn't feeling the love.

manderson89 3y ago

Reminds me of the Damian Conway quote "Documentation is a love letter that you write to your future self"

pwdisswordfishc 3y ago
So documentation is only written by narcissists?

thebruce87m 3y ago

I guess I’m writing hatemail every day.

ThalesX 3y ago

Sorry next developer, I'm on a tight deadline, used to love this craft, now I just do what the product people tell me to get a nice paycheck.

Arisaka1 3y ago
Yep. Yesterday I ran into a job opening asking for "Java developer who delivers 3x faster than the other developers" in one of the bullet points. It's such a weird point to emphasize that you want speed with no concern to trade-offs, and the maintainability and scalability of the codebase will be the first victims sooner or later.
- rpastuszak 3y ago
  Sounds like they're looking for a person who'll work 3x faster than the rest of the team by taking shortcuts and slowing everyone else down.
- BugsJustFindMe 3y ago
  My personal experience is that the majority of developers I ever encounter at work (as opposed to within my social network) are usually slow because they're bad engineers who don't understand problems quickly, don't have the knowledge or experience to see solutions quickly, and in general don't think deeply quickly. It's not hard to 3x performance without sacrifices when the baseline is mediocre at best. "Fast must be cutting corners and not just actually better at programming" is a weird fallacy to hang your hat on.
  - 3-cheese-sundae 3y ago
    There is always a cost to everything.
    - BugsJustFindMe 3y ago
      > There is always a cost to everything. There's a huge cost to having engineers who are bad at understanding and solving problems. The cost of having people who are good at understanding and solving problems is supposed to be that you pay them more, but that's not how employment incentive structures work in practice because information asymmetry and stigma around talking about salaries.

beebmam 3y ago

In my opinion, good code is like a Brita filter. It does its job, will one day need to be replaced, and it should be easy to replace. More importantly: metaphors are not a healthy way to understand an idea. Ideas are more nuanced than a metaphor could possibly account for. Abstaining from metaphors might not make for a catchy headline though.

xupybd 3y ago
In my opinion, metaphors are like a picture. They can communicate vast amounts of information very quickly but can have inaccuracies. You should expect some additional nuance when receiving a metaphor.
dmbche 3y ago
Little pushback here - metaphors are great tool to understand something, and can convey some meaning more efficiently than other means. But "the map is not the territory"!
- themodelplumber 3y ago
  The territory isn't the territory either, so no big deal!
Minor49er 3y ago
Metaphors are also ways of communicating ideas. A good metaphor is as simple or as complicated as it needs to be in illustrating a new concept
- KarlKode 3y ago
  Problems arise as soon as you (ab)use a metaphor (used to explain a higher level/adjacent problem) to explain concepts it was never meant to model. Example: Array of items as a shopping cart: how do you efficiently remove an item from the array (as you can from a shopping cart)?
  - deleted 3y ago

aye01 3y ago

fuck the guy after me. I write good code for my own sanity and so my OCD doesn't make me want to refactor it all later. it's like saying save the trees for your grandchildren or the future generations. fuck them, I want a clean environment for myself gosh darn it!!

NetOpWibby 3y ago
Had me in the first half

nashashmi 3y ago

The next developer ruins your code like new twitter runs old twitter or new arrogant engineer overwrites old humble engineering.

rpastuszak 3y ago

1) "Code sober, debug drunk" It's harder to read the code than to write it so if you can barely comprehend the thing you just wrote, you probably won't understand it in the future: https://sonnet.io/posts/code-sober-debug-drunk/ https://sonnet.io/posts/code-sober-debug-drunk/ 2) I think it's more like speaking with ghosts (including a spoiler for The Sixth Sense): https://sonnet.io/posts/emotive-conjugation/ https://sonnet.io/posts/emotive-conjugation/

majikandy 3y ago
>it’s harder to read code that to write it Isn’t this only true of bad code? Good code is almost certainly the other way round, harder to write than read… just like a really good book was much harder for the author than it was for you, the reader.
- ezekiel68 3y ago
  Code isn't a book. The quote you call into question is semi-famous and I believe the idea is that it's relatively difficult to jump into one code unit of a larger system and get back up-to-speed because one must fill the data cache of their brain with all the considerations for why the author may have done things in a certain way. The algorithm choices and edge cases and exceptional logic paths were clearer to the one writing the original at the time.
- rpastuszak 3y ago
  I agree with the sibling comment. > just like a really good book was much harder for the author than it was for you, the reader. Now, I suppose this could work for a nested narrative novel, where the reader is meant not to just read the book, but to rewrite and expand it as they're reading it. Adding new ideas, new sub stories on the way. Think 100 Years of Solitude blended with Italo Calvino's Invisible Cities. Seems like the [*]Bible is a good literary example of an async collaboration similar to code: notoriously hard to interpret, and full of dubious historical information and contradictions. I know that Christians call it the "good book", but most of them don't use the word "good" in the same way they'd use it to describe a Nabokov or Eco novel. [*] or most ancient religious texts, like Avesta

ModernMech 3y ago

Plot twist: that next developer is you. Love yourself!

malikNF 3y ago

I prefer the quote that goes "Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live."

majikandy 3y ago
This. I was about to mention the same quote. This quote alone has served me well over the years. Sounds jokey but if you live by this, it’s brilliant.

mellosouls 3y ago

This blog entry is a much nicer and more graceful version of the old adage about writing your code like the next guy is a psychopath who knows where you live...

more_corn 3y ago

Good infrastructure is too. I had a colleague deploy the power whip for the last available rack position on his way out the door. Years later when I desperately needed that rack to keep the site up I was able to roll it in and light it up without waiting 6weeks for an electrician change request. He saved my bacon by thinking ahead. It was a gift he gave me, never mentioned and was not around to receive thanks for. I aspire to be more like him in everything I do.

hkon 3y ago

Good code is not like art, such as good books or paintings. No matter the quality of your code, if the product or service is not a good market fit. It will be retired. No one will stumble upon it or pick it up after it's gone. Knowing this, the only reason for putting effort into it is to make it easier for myself.

majikandy 3y ago
The two aren’t always mutually exclusive, you might be writing code for a good market fit that stands the test of time and needs maintaining. The times you appreciate it are actually when you open something and it’s nice and easy to change and you realise you were the one who wrote it. But real developer happiness comes when you have the same experience and someone else wrote it.
- hkon 3y ago
  Indeed, I'm just trying to highlight your efforts as an 'artist' might be wasted. I recently worked on a project with some seriously clean code. My job? Shut it down. This made me sad.
mostlylurks 3y ago
> No matter the quality of your code, if the product or service is not a good market fit. It will be retired. No one will stumble upon it or pick it up after it's gone. This applies to artistic endevours like books and paintings as well (especially those two, since markets for them are very oversaturated). Your technique might be masterful, but if your art doesn't align with current trends (along with a number of other factors), it'll drown in the endless barrage of other art, and nobody will stumble upon it or pick it up, even if it's still available.
- hkon 3y ago
  Yes I thought about that, I was thinking in the sense that someone in the future might actually stumble upon a painting or a book. They won't with proprietary forgotten code.

xupybd 3y ago

> The beauty of our creations, however, is not judged solely by the elegance of our algorithms or the efficiency of our code, but by the joy and ease with which others can build upon our work. Often this is not true. Our creations are judged by the user. They don't care how good it is under the hood. They care that it works correctly, that it's easy to use and that it's as fast as they need it to be. Your boss should care that it's well written because that should mean it's cheaper to maintain. But, they don't look that far into the future when evaluating your performance. So, often they only care about how fast you did it and how happy the customer is with it. Our industries incentives don't often align with good code.

deleted 3y ago

[deleted]

swayvil 3y ago

The computer in this metaphor is what, a marital aid?

henning 3y ago

dear future developer, nothing matters and code will still be hard to read even if I try my very hardest to make it as good as i can. the world is dying and we are doing our best to kill it. you having a hard time understanding my code is not really anything that can be fixed. it pales in comparison with the actual problems the world faces. tough it out or rewrite it. sorry

ugh123 3y ago

Meh. I've seen teams and projects bogged down by "good clean code" rules and nit picking code reviewers. These folks, typically "staff" engineers, over-police the repos and care more about clean code than delivery and execution. I'm waiting for the day where AI/co-pilots can enforce team and industry best-practices, style, maintainability, testability, etc before the code is even committed. Call it "uber-linting" and get rid of code reviews.

Rietty 3y ago
Can't you already do that with pre-commit hooks? We use those at work to check a lot of stuff like that before a commit ever goes through.
- ugh123 3y ago
  Of course! I'm talking about the kinds of checks and scans that are made on the code during the pre-commit hook
crucialfelix 3y ago
I'm working with someone who asks me to remove documentation that summarizes what a function does. (The whole codebase is stripped bare of documentation.) Copilot can write implementations based on comments. Soon I think it could flag potential errors if code doesn't do what the comment claims it does. Then we can do that in code checks.
- randomNumber7 3y ago
  This mentality drives me crazy. I mean i agree that most comments are bad, but some high level description what a function/object/library does or how it is supposed to be used is something different. When it misses then I have to read the ** code to use the ** thing. And I am not interesed in that at all. Maybe they do this so someone has to read their "good" code.

m00x 3y ago

After more than a decade of development, I've come up with this mindset: I don't really care that much about the developer, and care a lot more about the users of my product, especially since that developer is usually me. If I'm unsure of the value I'm adding, or if the ability to do something is greater than its quality, I will take shortcuts if needed. If the codepath is critical, or if doing so is dangerous, I will take my time on the quality and the foolproofness. I will be pertinacious in this mindset, and if managers try to rush me, I will remind them of the consequences of failure and log everything. I've seen too many developers (myself included) spending weeks and months on perfecting something that's never used, or barely used. The latter issue of not spending enough time is a lot more rare, but does happen.

anon7331 3y ago

It's a very nice way to imagine good code. More likely, someone inexperienced or less caring will come along and edit it just enough to turn it into mediocre code and no one will care anymore.

loph 3y ago

Truth. Years ago a wise man told me "The compiler is not your customer. The next person who maintains this code is your customer. It might be you."

m00x 3y ago
The customer is the one using your product, not the one maintaining your code.
- ezekiel68 3y ago
  A common reply, but misguided. A corporate coder who is not also CMO and CEO does not produce products for the end user. They produce code units which, after build, deploy, and integration, become useful building blocks in an overall solution which may (the company hopes) be a product for the end user. From this standpoint, the code they write will often be 'consumed' by other coders and by future themselves. The consumers are therefore coders.
  - m00x 3y ago
    Sure, but usually you develop an interface to your service/code, and they shouldn't have to know the internals. If they have to look at your code to figure out how to use it, you've already lost. Hence the code isn't the product, it's the means.

imoverclocked 3y ago

As someone who has gone back and read my old code as well as a lot of others old code, there is no such thing as good code. IMHO, the problem is one of cultural context which is often not shared between generations of coders. Languages and best practices can change so violently that best-practices one decade are often anti-patterns in the next. As a codebase outlives its best-practices, do you stick with them and extend with those same anti-patterns or do you implement new things with a different mindset than the rest of the code? -- If you break with tradition then you are making it harder to understand the codebase as a whole. eg: why do we have a mix of procedural/OO/functional/... methodologies with spaghetti code at the core? -- If you refactor everything then you are definitely breaking something. eg: you have a 10M+ line java codebase with transformations bringing you into the 2020s from coders who originally knew C and Java 1.4. -- If you keep with tradition then are you writing the best code possible? eg: would you willingly use goto of some variant in new code if you jumped into a Cobol 74 codebase? I think what the article really wants to talk about is "clear" code or "understandable" code and not "good" code.

woooooo 3y ago
Style changes over time, but factoring is evergreen. Something could be written using Java 1.4 idioms with good organization and factoring, or using the latest functional hoohas with everything all mashed together. Or the inverse, of course. If the structure of the code matches the structure of the problem, the implementation style is a much smaller deal.
38 3y ago
> there is no such thing as good code definitely not true. this is good code: https://github.com/torvalds/linux/blob/master/fs/file.c https://github.com/torvalds/linux/blob/master/fs/file.c this is good code: https://github.com/golang/go/blob/master/src/strconv/atoc.go https://github.com/golang/go/blob/master/src/strconv/atoc.go its formatted, commented, direct. the fact that you struggle with writing time tested code does not mean that everyone does.
- grepfru_it 3y ago

renox 3y ago

The emphasis on tests made me laugh: I work on a project where it's mandated that all the code is covered by Unit Tests. In my estimate the time to make UT is 3* the time to create the code. And no, nobody use TDD in this project because it takes 3 minutes to compile one UT (C++ sigh), so we all do 'post coding' tests. While sometimes the UTs do help, they're also a huge burden: wants to fix some code? Well you also have to update the UTs..

bcoughlan 3y ago
Overly granular tests are a scourge of our industry, unless you’re writing a widely used utility library. It leads to tests that become a useless burden for even mild refactoring. Writing larger test cases that test the actual functionality is a game changer. With Testcontainers and good mocking tools you can spin up a real version of your app with external dependencies mocked and faked, and write test cases against the same input layer your user uses. If your test fails you can be pretty sure it’s because you broke something. This is a layer between unit and integration tests that you don’t read much about. I call them “service tests” (coming from a microservices world). Investment is still needed though to reduce the effort of implementing tests, like extracting common fixture code so that every test doesn’t need long winded setup code. Also snapshot testing libraries take the pain out of writing assertions. I am speaking from the API based backend world so YMMV. Once you’ve worked this way it’s hard to go back. Any developer can come in and confidently make changes. You spend way less time investigating regressions and broken environments, so you can release more frequently (which takes a whole other layer of pressure off the team)

ubermonkey 3y ago

I've always said "write good, well-commented code as a favor to whatever poor bastard has to work on this in three years, and realize that the poor bastard in question may well be Future You."

deleted 3y ago

[deleted]

yash8141 3y ago

lol use this analogy for surgeons. Every heart bypass is love letter to other surgeon.

laserDinosaur 3y ago

An article on HN a while ago posited that 'bad code' is directly correlated to forgetting what the code does over time - not the code quality itself. When you green-field a project, everything is fresh in your memory and the code feels great. When you come back to the exact same code a year later you you've lost your landmarks, there's workarounds you don't remember why they exist, suddenly you hate it, ugh this code is terrible! So you re-write it, making you more familiar with the code again and making it easy to remember - suddenly its good code! I try to keep that in mind when writing my code. Sometimes its comments, sometimes its documentation, sometimes its CleanCode™, sometimes its big blocks of text explaining why the heck a certain class exists, but my approach is "Write it for myself in a year when I can't remember what the hell half this stuff does", using every tool at my disposal to achieve that.

henry_bone 3y ago

"At the start of my book, Learning JavaScript Design Patterns, I say "good code is like a love letter to the next developer who will maintain it". It is an intimate correspondence, from one developer to another, spanning time and space." Seriously?! It's simple. It's a matter of respect, and treating others as you would like to be treated. It's no fun trying to figure out the "why?" of some code you've inherited responsibility for. It can be frustrating and time consuming. So why would you put others through it. Make the code and the reasoning behind it as clear to the next dev as possible. Explain it with comments. Refer to issue links. Make it so that there's minimal - preferably zero - unnecessary digging for the next poor soul who'll work on it.

midoridensha 3y ago
>So why would you put others through it. Because I've found there's a bunch of developers who apparently think it is fun to figure out the "why?", and they code accordingly. >So why would you put others through it. Because they think their code is "self documenting" and perfect and that anyone that can't immediately understand their code is too dumb to be working with it. >Explain it with comments. We just had a discussion here in the last week or two where people were actually saying that comments are completely useless and should never be used. >Make it so that there's minimal - preferably zero - unnecessary digging for the next poor soul who'll work on it. Sounds great to me, but in my experience it's a minority of developers who agree with you. It makes working on others' codebases very frustrating in most cases.

osigurdson 3y ago

Or yourself, years later after you have forgotten about it.

drbojingle 3y ago

Unless they look at it and say "there's no abstractions anywhere. Why did they use 'THAT' lib? Full rewrite needed. Hate this code in paticular." Good code is contextual and subjective.

pohl 3y ago

So my side project is like Narcissus having a wank, then.

yodsanklai 3y ago

Developers love to debate about these things, but everything has been said already. I've noticed that the better the developers, the less they engage about these topics.

000ooo000 3y ago
Developers who enjoy discussing what makes code good are worse developers than those who don't enjoy discussing it? Is that the thrust of your comment?
ezekiel68 3y ago
> but everything has been said already. It turns out this is true for well over 90% of relevant topics on the planet. Every year in the US, over 4 million people turn 18 years old and over 3 million people of various ages die. If we contract this dynamic to people who enter and leave our industry, it becomes clearer why it is not only helpful to say what has been said already, it is vital. The above has already been said also.

throwawaaarrgh 3y ago

Code is communication about as much as a septic line is communication to the next plumber or homeowner. It's a part someone will have to maintain after you. But it's also just a septic line.

mattgreenrocks 3y ago

After almost 20 years of writing the best code I can muster as much as I can, I’ve come to understand that most people won’t ever really appreciate it for the effort you put in. Many won’t even notice; they’re too preoccupied with their own lives to open their eyes to what is there. Nor do they give a damn about mastery. But, that doesn’t mean it’s a waste. I don’t think I’d do much differently in retrospect, except be far more cautious about where and who I spend time around. Even this very thread has some pretty bad vibes: “who can say what good code is?” “good code can’t exist with deadlines.” I feel really bad for junior/intermediate devs that read this stuff and internalize it.

Gigachad 3y ago
Usually the situation is someone has meticulously crafted some perfect system which can be extended and reused in many coherent ways. And then that person leaves the company and no one else truly understands how it works or was meant to be used so it gets a series of hacks and patches applied to it which violate the original design which is known by no one at the company. For most projects this is not that big of a deal, the component gradually becomes less coherent and the original requirements change so much that one day someone will decide that the whole thing will be rewritten from scratch.
- thumbuddy 3y ago
  And this is why Go lang exists... The trade off is screw brilliant engineering just make it simple so other people can build on it easily. Not saying it's my favorite, but it has it's merits long term.
  - AdieuToLogic 3y ago
    A semantically weak language does not reduce the inherent complexity of a system, as problem complexity is constant. What Go does is encode solution complexity implicitly throughout a code base. This is the same effect JavaScript often has.
    - 3y ago

miki_tyler 3y ago

FTFY: Good code is a love letter to your future self.

8note 3y ago

Something I'd consider for the good code is leaving open nice easy tasks for future developers to pick up so they can get a sense of how the codebase works. Just reading isn't as good as interacting with it

JonChesterfield 3y ago

Sometimes I go to change code to do a new thing and it is easy to do. The new cases fit in, the existing system doesn't explode, all is good. Sometimes the code is beautifully factored and tested. Maybe even documented. It then proceeds to fight against the new change. Maybe the type invariants fail everywhere for reasons that price spurious. Maybe code far away makes dubious assumptions and breaks in response. In the worst case, it's beautiful nonsense held up by undefined behaviour and the language has come to collect the tax. I like code that can be changed to do new stuff without everything around it exploding. That's probably what I'd call good code. It's in the context of tolerating future requirements well as the future is now. I do not see such code often.

renegade-otter 3y ago

Write good code. Professional code. Simpler and easier to understand code. That’s it… Some Leetcode jock will come in one day and rewrite it anyway, or a new CTO will crash the joint holding a bathroom sink and make your code an orphan. Or the company will just disappear. The code that i write like my own is, well, my own. Because that’s the code I come back to years later and I maintain, and always will. Everything else is ephemeral.

ww520 3y ago

I largely follow the forgetful programming practice, i.e. I will get it out of my mind after finishing it. This forces the code to be clear and consistent so that I can pick up on it easily if I need to look at it again.

tmaly 3y ago

If the headline is the case, then I have been in some bad relationships.

whoknowsidont 3y ago

The only good code is no code. All lines of code will decay, teams will move on, assumptions will change, refactoring efforts will be non-exhaustive, dominant skill sets and experience in the industry will shift. This is fairly tired conversation and while superficially interesting, there is simply no way to define good code except through local consensus of the people writing and reading the code. But that's as far as it will go, and time will will take what's owed to it.

AdieuToLogic 3y ago

While I would not categorize good code as being "a love letter", I would say that it behooves software engineers to remember that the solution they encode is read many more times than it is altered. Like, 1000x more.

humility 3y ago

'Good documentation is a love letter you write to your future self' vibes anyone?

patrulek 3y ago

What a shame im not romantic at all.

k_bx 3y ago

So writing good code is gay?

p0w3n3d 3y ago

Very often writing good code is a love letter to your future-self. So many times I blamed the git repo to check who was so stupid to write such code, and it was me...

quectophoton 3y ago

> Good code also adheres to established best practices, [...] Controversial opinion, but in my experience so far people usually say "this is best practice" as a way to avoid thinking, or to masquerade personal preferences. Not always, but more often than not. As soon as you ask "why is it a best practice?", "what are the consequences of not following this best practice?", "since 'best' implies there's a 'not-best', what is an example of the 'not-best practice' that this wants us to avoid doing?". The answer is usually something vague and handwavy like "because it's more scalable", but if you challenge that by saying "what do you mean with 'scalable'? can you give an example?", you usually won't get an answer. Doing stuff without understanding the reason, that's cargo cult. To be clear, I have nothing against people saying "I understand the code better like this"; it's subjective but honest, and it doesn't try to pass a subjective argument as if it were an objective truth. What I dislike is people saying "this is best practice" like an absolute truth that must be blindly followed and never challenged, without even considering the circumstances of the current project. Please spare me from turning a simple HTTP CRUD of 4 endpoints into an overkill Icosahedronal Architecture with a reason like "when we need to write an v2 this will make it easier without needing a rewrite!"; because I know that when the time comes for an v2 you'll rewrite from scratch anyway because then you'll want to use the new and better(tm) Perpendicular Riemann Zeta Architecture.

utresk 3y ago
I understand the spirit of your comment here, but in my area of experience, security, there are certainly objective “best practices”. There is almost always pushback on security considerations, and partly because those methods quite often change and improve with time. The term then becomes a blanket phrase that captures the constantly evolving landscape and necessity of accepting those new changes. You’re right that it is becoming over used. Like most abridged language, once your favorite becomes popular a new way to express the same underlying idea usually comes along.
- quectophoton 3y ago
  Oh yeah, no doubt there. If a nobody like me writes a random blog post saying my custom way of doing ThisSecuritySensitiveThing is the best, at the next microsecond I'll have half the world linking me to like 20 different papers and 5 real incidents proving why I'm wrong. And I wouldn't be able to wiggle my way out of that criticism with responses like "but it works for us".

pictur 3y ago

I don't think being so romantic helps much. To take these articles seriously is to believe that there is such a thing as good code. but I don't think there is a good code that will make everyone happy. I understand the effort it takes to make the code something permanent, but I think the code has to be something that has changeable and the processes have to adapt.

misja111 3y ago

Here are my 2 cents, after 25 years of development in several companies. If you want to do the next developer a favor, your codebase should be simple to understand. Period, that's it. Simple to understand means: 1. Don't use fancy design patterns, FP constructs, performance optimizations etc. Unless the use case specifically requires it. 2. Code should do whatever it needs to do to fulfill its business requirements. Nothing less and preferably also nothing more. 3. Readable code beats documentation: only document the 'why', and only when it is non obvious. If you find you're documenting the 'how', have a second look if you can write your code in such a way that it explains itself. 4. Explain how to build the project, run tests and whatever else is non obvious in a Readme file in your project. Documentation anywhere else, such as on Confluence, will not be maintained or read.

The_Colonel 3y ago
Where "fancy" is relative. There was a time when Java 8 streams were fancy for many devs, today it's the default way to manipulate collections. I think the code should be "optimized" for the expected audience (of other devs). If you're a single rock star in a mediocre dev shop, you need to code differently than when you're part of a team of MIT PhDs.
- kaba0 3y ago
  That’s actually a very good point!

haspok 3y ago

> (...) and the practice of Test-Driven Development (TDD) are indicators of a carefully crafted 'love letter'. I call BS on this one. TDD is usually a sign of a struggling junior and results in the worst code quality possible. Also, the next developer is in many cases myself, months later, trying to fix something or adding a new feature. I wouldn't care about other developers, because everyone has their own style and niggles, it is enough to cater to my own niggles, can't be bothered about others. And I also don't make a fuss about code written by others, as long as it meets some minimal standards.

dingi 3y ago

There might be love letters like that but any codebase that has been around for couple of years is not that. I'm yet to see any codebase in the industry that I can describe as a Love letter. I'm starting feel like I'll never find such a thing. Just make do with what you have. They are not paying you for reading love letters. It's mostly for maintaining and putting band aids over shitty code bases.

jeffrallen 3y ago

Sometimes it's not a love letter, sometimes it is a note saying "yeah, I don't like this anymore than you do, let's just get this over with so we can go take a coffee break and come back to something more interesting". Code works. Not all work is fun and beautiful, some work is not even worth doing. But making something work because it needs to work is also worth doing.

SleepyMyroslav 3y ago

I have come to conclusion that there are different types of people who work with code. There are writers. They can not stop writing. If something tries to stop them they move on and keep writing. Most of the code around is written by very small amount of people. Personally I came to terms with myself for not having to do that. Some companies who rush things to market do not understand it but it is okay with me. Looking back at years and shipped projects I do not trust such metaphors as in the article. I prefer other pov. Where I grew up one songwriter and performer coined it (sorry at incorrect translation) "[they] write as they breathe. It is a natural order of things". So if I do not like working with someone's code I have to move on.

justincredible 3y ago

[dead]

drderidder 3y ago

Including your future self.