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.
Good code is like a love letter to the next developer who will maintain it
201–210 of 274 posts
Re: Good code is like a love letter to the next developer who will maintain it
#202After 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…
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 d…
This is true if you assume that the abstractions identified by the original author is correct and adequate for the life of that app. Usually, it's not the case. There are slight deviations that makes previous abstractions unusable for new requirements and the new dev has to start from the beginning
Re: Good code is like a love letter to the next developer who will maintain it
#203Precisely 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.
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 grea…
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.
Re: Good code is like a love letter to the next developer who will maintain it
#204Earlier quoted context omitted.
When I do personal projects for myself, I try to comment them really well for this exact reason. Just today in fact I was trying to update some code I wrote two years ago because one of the underlying tools broke. I was very happy with past me for commenting the workflow of that tool so I could easily work around it.
A good alternative is code without comments that communicates just as well as that code without the comments. Not necessarily better but less likely to slip out of sync with the comments upon change.
It's not an alternative, you can't obviate the need for comments with code.
What you're supposed to do is write the code as clearly as possible and then add comments for anything you couldn't manage to express in the code. Usually that'd be all the context around why the code is the way it is and isn't the way it isn't.
Re: Good code is like a love letter to the next developer who will maintain it
#205After 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…
Most people might not appreciate "good code" but they'll sure as hell un-appreciate bad, unreadable code.
Re: Good code is like a love letter to the next developer who will maintain it
#206After 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…
One of the saddest moments was hearing a smart person with barely a few years of experience insist that code always degrades in quality and there's nothing you can really do about it...
Never saw them try.
Re: Good code is like a love letter to the next developer who will maintain it
#207> 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', w…
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…
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".
Re: Good code is like a love letter to the next developer who will maintain it
#208After 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…
I’ve hunted down contact info and emailed a dev who’d left the company to thank them for the clean code they left behind. I encountered their code while debugging weird behavior in a legacy feature. The code structure was immediately intuitive and comprehensible. Just the right amount of detailed but not superfluous commenting. Beautiful. It made my day so I let them know!
I never had code where I was like, oh this has too many comments.
I never get this sentiment from developers. I've had reviews were developers wanted me to slim down & rewrite comments.
It's often hard in the moment to understand what's obvious or not. Just always writing a comment even if it's obvious can save a lot of pain in the future.
Re: Good code is like a love letter to the next developer who will maintain it
#209Earlier quoted context omitted.
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.
Go isn't my favourite language, but I disagree with that: a language being being simple does wonders to reduce the possibilities of accidental complexity added by complicated features that are unnecessary for the business. But of course it's still possible to make a mess: I've seen someone who created an ad-hoc object model (with its own structs, plus multiple inheritance and all) on top of Golang and wrote a few app…
I find Go bizarre... 90% of the code written in it seems to consist of checking for errors and passing them around. And yet, every time I've had to interoperate with somebody's Go code, it falls apart immediately because of significant processing errors that it seems like somebody should've caught, like a null-pointer dereference, or a wrong lookup into a map, or a (de)serialization error.
_Every time_ the programmer responsible seems blissfully unaware of the possibility of said error and I need to provide a test case for them to reproduce it. Their mental model of the code they think they wrote is wrong compared to the actual code.
The culprit is usually something like an `interface{}`, granted, which people then excuse as being un-Go-like... but if all the language's supposed ease and robustness fails as soon as it encounters anything outside of its own ecosystem, then it's not worth much. All the busywork around errors starts to look like a cargo cult to make the juniors feel like they're accomplishing things when they're just glueing things together.
No other language I've seen has it so bad. Rust is particularly good in this area, and seems to view it as its own responsibility to interoperate cleanly, providing sane and powerful ways to opt-in/out of Rust's semantics at the edges. Even TypeScript makes it easy to partially or gradually type when you need to, and this seems much safer in practice to me.
Re: Good code is like a love letter to the next developer who will maintain it
#210Earlier quoted context omitted.
I’ve hunted down contact info and emailed a dev who’d left the company to thank them for the clean code they left behind. I encountered their code while debugging weird behavior in a legacy feature. The code structure was immediately intuitive and comprehensible. Just the right amount of detailed but not superfluous commenting. Beautiful. It made my day so I let them know!
I never had code where I was like, oh this has too many comments. I never get this sentiment from developers. I've had reviews were developers wanted me to slim down & rewrite comments. It's often hard in the moment to understand what's obvious or not. Just always writing a comment even if it's obvious can save a lot of pain in the future.
You have never seen a comment that helpfully explains that getUsername() returns a string with the username of the user that the method is invoked on?