Hacker News Reader

Comment by mattgreenrocks | Hacker News Reader

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.

View on HN

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?

Or the classic result of updating the code but not updating the comment:

//Returns the user's full name return user.email;

Okay but when you see that why not just take 30 seconds and update the comment?

Edit: if even 30 seconds

in a collaborative environment, it's rarely 30 seconds to make such a change though. usually you have to make a commit with message, make a PR, submit the PR and get someone to review it (many orgs require code review for every change), then merge it. And each of those steps usually require you to context switch from whatever else you were actually trying to get done.

Now, if you're already changing that part of the code/file, then sure it's pretty low overhead. But for something as simple as that function, I'd probably delete the comment entirely.

For something as small as a code comment change, it's super fast, and honestly not worth the local branch stage -> commit -> push flow. Assuming GitHub, just edit it within the browser (if you find it in your editor, press the hotkey for opening the source in GitHub, if you're already in the browser, great). Make the change, hit commit (which defaults to a feature branch, you can change this), and then GitHub automatically opens up a PR template for your to then hit "create." Add reviewer(s), enable auto-merge, then forget about it.

If something like that is generating a lot of bureaucracy and time-wasting, then there are several other pressing problems that are much worse than that.

My company is heavily regulated (finance) and highly bureaucratic, but I still just merge those PRs without waiting for the CI or without even bothering clicking approve, I just look at it. When I find one myself I just merge to master or edit in Github directly. No auditor has ever batted an eye to that.

yeah that's an issue, but the much easier to update a comment then an extensive suite of unit tests. And in my experience the payoff of good comments is about the same, minus the cost.

I'd rather someone over does it then under does it.

The issue is that most things are obvious when you write the code, but that it's often not clear what's not obvious in the future.

So if you just get in the habit of explain every function it will lead to a more understandable codebase.

Obvious is and will be what the code does, not obvious is and will be why the code does it. I hate when people write comments explaining what the code does, I can just read the code and I will know. Why write it twice and open the possibility for inconsistencies? Is the comment wrong - forgotten to be updated maybe - as the code does something different then the comment says or does the code have a bug and it should actually do what the comment says? Also if your code can not be easily understood, then improve the code instead of trying to explain it in comments. Good reasons for comments explaining what the code does are few and far between. On the other hand I want people to comment why they do what they do and why they do it the way they do it, that are things that are hard or impossible to infer from the code. Unfortunately, at least in my experience, people tend to write way to many what and way to few why comments.

I have seen plenty of it, but it doesn't bother me at all, especially with IDE syntax highlighting. The near-zero-documentation policy seen in some codebases bothers me 10x more.

> 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?

Yes, but that's not all that annoying when the opposite is you stumbling upon a service pattern with uncommented methods along the lines of CVKUser getCVKUser(int cvkId, ...) or VFUser getVFUser(int cktId, ...), without having any idea what the person writing the code 4 years ago was thinking.

You've no idea what CVK or VF is supposed to be and have to spend an hour looking at both of those classes, as well as everything that surrounds them in the codebase, as well as what cvkId and cktId are supposed to be and why cktId supposedly matches VFUser, to do enough code archaeology, so you're able to figure things out confidently.

That said, there is little use in code comments that explain WHAT the code does for trivial bits of code, instead of comments that explain WHY it works like that (like a more sane version of having to dig through Jira tickets, or years of commit history, or old pull requests, or whatever) or what other considerations there are to take into account (since separate docs won't be read as much and Jira tickets won't always have the technical information).

I've seen comments that basically amount to "here we set the variable to 5". Comments also come with a maintenance burden, it's easy to forget to update them when the code changes.

The issue I’ve seen in older codebases is comments not being updated when the corresponding code updates. This usually is more of a problem for comments that are not local to the code, whether they are in docs or in a separate code file. Once enough of that creeps in you start distrusting comments and thus stop reading them.

> I never had code where I was like, oh this has too many comments.

It happens. Even worse is when the code has been updated but the comments have not. I've picked up the habit of double checking comments with git blame.

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.

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.

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 apps in that style. But not having the features in the first place can help.

Then why not assembly is the ideal program language? Ad absurdum, that’s the simplest, isn’t it? Each line does something completely trivial.

Abstraction is the only tool we have to even hope to manage complexity. Unfortunately there is no way to force good abstractions, finding out the perfect abstraction is the deal of the art. Maybe I’m wrong on this, but I’m on the elitist view that the industry really shouldn’t try to replace a single senior developer with 10 juniors that monkey patch based on stackoverflow/chatgpt. I don’t even see how that makes financial sense, if one values product quality.

Because, obviously, too little abstraction is as bad as too much abstraction. The way to combat excess is not with more excess.

There are no automated to enforce good abstractions, but languages and tools can serve as a way to shepherd programmers into avoiding or preferring certain patterns. This is an argument as old as the programming language field itself.

For some people Golang strikes a good balance. I'm not one of those people, but I have learned to respect it.

Assembly is a lot harder to write correctly/safely than go lang is. Comparing the two seems disingenuous.

I do agree with you to some extent about not replacing senior engineers. But a "bad" senior engineer who is "too smart" for their own good can do more damage then juniors following a template.

All things in balance for sure.

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.

I personally prefer rust over go as well. That said, some rust code is genuinely scary in a way where you do have to wonder if anyone else could maintain it without rewriting it themselves. There's a lot of complexity that although is visible in the syntax is too much for anyone to keep a mental model of - at a certain level of complexity.

Kindly written rust is fine, same goes for a lot of languages. The issue is, sometimes really smart people have no interest in kindness. There are a lot of social factors that go into people writing monstrosities "gotta look smarter!" "Gotta have job security!" "Don't want anyone to call me out on this".

I write dumb code 99 percent of the time. I'll never get promoted for it, but people know exactly what it's doing.

For anyone interested in a discussion about the concept of systems not being understood by newcomers, I can recommend Peter Naur's Programming as Theory Building: https://pages.cs.wisc.edu/~remzi/Naur.pdf

Just commented the exact same thing without checking if someone else also posted, because it is not that well known for some reason.

Right to the spot, thanks for sharing this! I've always thought that having a decision log of justifying design/implementation choices which are somehow surprising would be healthy thing to do.

That's often the rationalization for most "perfect" and "ultimately reusable" code I see, however what I've seen too many times is code that ended up turning into shit even when the creator remained the sole maintainer.

Blame often gets passed upwards to some product manager or sales coming up with some outlandish business requirement, but honestly the real reason is that the code wasn't that flexible to begin with.

Which is perfectly fine, not all code can be flexible and infinitely reusable. Perhaps we should stop forcing every single file to be.

> Usually the situation is someone has meticulously crafted some perfect system which can be extended and reused in many coherent ways.

Very rarely is that good code, even if you actually do understand the design. Most of the time, when you come to extend it, it turns out to be in a slightly different way than the original author had expected. Now you've got the complexity of solving the original problem (inevitably) and the new problem (also inevitable) and also some other problem that might have needed solving but didn't after all (not inevitable).

Most of the time, code that is easiest to modify or reuse is the code that does its current job in the simplest way possible. That doesn't mean you can't create reusable abstractions - doing so often does make the code simpler even for just its current job. And that usually ends up aligning quite nicely with what turns out to be (almost) what is needed for other tasks anyway.

I agree wholeheartedly. Code which is "designed to be extensible towards future use cases" very often expects the wrong kinds of extensions and actually makes it more difficult to extend it because it's necessarily more complicated.

> Most of the time, code that is easiest to modify or reuse is the code that does its current job in the simplest way possible.

Very much this.

The exception here I think is the choice of data structure. If you know that code will be extended to accept additional fields it makes sense to be sure to use an extensible data structure or to ensure that side effects are contained correctly (a good idea anyway) and in a way that allows extensibility when they must be changed.

> If you know that code will be extended to accept additional fields

Well, you rarely know, more often "guess".

There's an important distinction between public and private interfaces. With public interfaces, I contend that it does make sense to think about future use cases and put in some flexibility even at the cost of a small overhead.

That seems reasonable.

This can be condensed into the simple, age-old rule: don’t worry about DRY or reusability until you’ve copy-pasted the code into a third place.

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

I too have met many developers who have developed the mindset that good code is impossible. That is really sad.

Imagine a carpenter that says straight cuts aren't possible, just because they never maintained their tools and the last 10 cuts came out wrong.

Of course good code is possible. But not every person is going to write it and it is not going to happen under all possible circumstances and in all given project structures.

Our job as professional software people is to be able to judge how to create the circumstances and the time frames under which good code can be written — and to say No to projects that cannot be written by us and our team. This isn't always a simple thing, but it must be done.

The saddest aspect is that you see many experienced software developers who never experienced things working well. And as someone who sometimes writes code for fun I cannot understand that at all. What I get is that throughout your professional life you can never had the chance to be in a project where you could write good code. However you can write good or even perfect code at home where nobody pressures you. And if it is possible there, why wouldn't it be in a professional context?

Now imagine a carpenter who can build the most beautiful, elegant piece of furniture in 30 days, but you force them to make it in 10. Or you forbid them from using a certain tool. Or force them to use a tool you prefer. Or …

Yes, not every programmer cares about good code. But of those that do, also not all of them can agree on what good code is.

And not all good programmers can write good code, for one reason or another.

It is way less black and white than good vs bad/mediocre programmers.

> Now imagine a carpenter who can build the most beautiful, elegant piece of furniture in 30 days, but you force them to make it in 10. Or you forbid them from using a certain tool. Or force them to use a tool you prefer. Or …

Some of these are not like the others. Not allowing a carpenter to use the most suitable tools is petty. Not allowing them 30 days may make sense depending on the business context. What if it's a stool that's going to be sat on once and then thrown away? Or there's only 10 days salary in the bank but then an invester will see it and may pay for 100 days work?

Good code usually takes more time than bad code (depending on the reason!) and often it is worth that extra time (and the fight to get it). But sometimes it's better not to and that's OK.

Completely agree.

It’s all about trade-offs. Which many developers don’t - or just refuse to - understand.

My point was that without some context this kind of conversations - about good and bad code and good and bad coders - are not very useful.

Yeah sure, but in the context of my argument (it is sad that there are aoftware developers who don't believe the product of their craft can ever be good) it doesn't actually matter. Sure, maybe that just means coders have impossible standards that cannot be reached, ever. Or it could mean that typical projects tend to be manages in a way that leads to code that those who wrote it don't consider good (to such a degree where they don't believe good code is actually possible).

Personally I believe good code is an reliable, maintainable, transparent and well designed solution for a problem (or a set of problems). And that means for a small problem aome ad hoc script can be good, while for a big complicated set of problems an elaborate well coded project with a build system can be good code.

But what I believe is that there are ideal solutions from an engineering standpoint, and there are ideal solutions from an business standpoint. And those sometimes don't align with each other. E.g. when you solve a core problem that should really be dealt with properly with a quick fix that might be a cheap way to reach the short term business goals, but it could shape a lot of engineering decisions in the future in a bad way and maybe even become a business problem in the long term.

Well put, about the engineering solutions and business solutions. There is definitely big faps between business people and developers. They usually both think they are right. :)

I am not denying that at all. I know my share of carpenters and if they are in a pickle, they might take on a job like that, and swear about it like there is no tomorrow all the way to the bank.

What I found remarkable wasn't that there are badly managed projects, but that there are software devs who seem to think there is no other way than doing it like that.

Yep, I have met a few developers like this. A lot of them would not even question the situation or explain it is not a food idea doing things a certain way. They would just take the path of least resistance.

I think the abundance of jobs - maybe not anymore? - also added to the problem.

I’ve received countless CVs where the developer didn’t stay at the same job for more than a year, max two. Now, it could be that some of the jobs sucked, bit it is highly unlikely that all of them sucked.

But what is "good code", even? For some people that's thousands of two-line methods in hundreds of classes where each part is easy to understand. For others it is more direct code that is optimized for debugging, but not as aesthetically pleasant. Very often those two groups people dislike each other's code a lot. And there's even more other "groups" than those obvious two.

Does that question really matter for this discussion? Every developer will have their own flavour of what constitutes good or bad code, but independent of their flavour isn't a software engineer who doesn't believe in the possibility of achieving good code a somewhat sad thing? Imagine being a cook that doesn't believe in the possibility of cooking good food — sure what constitutes good food is a matter of discussion, but if you have a cook that doesn't believe in it that alone is remarkable in itself.

It does matter because what constitutes good code for some people is often terrible code for others, to the point of people making jokes about it [1].

With food, at least there is a wider agreement of what consists of good and bad.

[1] https://github.com/EnterpriseQualityCoding/FizzBuzzEnterpris...

But we are talking about self-judgment here. What does it matter which flavour of good you expect your code to be if you actually don't believe good code by your definition can be realistically achieved?

I agree with the sentiment, never said anywhere that it couldn't be achieved in a personal level. Just that defining "good code" is difficult. If you narrow down "good code" to mean "good to myself" then of course it is sad that someone doesn't believe in it.

On the other hand, I find that someone saying that "universally good code" is not possible as understandable.

I personally believe it is only really achievable in certain domains, for some others (especially for code handling a lot of essential complexity) it is borderline impossible to not have at least some uneven corners. And there's only so much you can sweep under the carpet of indirection.

Imagine that the carpenter already gets the wood cut from a far far away land, and has to make due to the way they were prepared.

After nailing a couple of them together, it has to send them to another far far away land, for some glue job.

Afterwards he gets them back, he applies varnish over the wood pieces, and sends them yet again to another far far away land for the paint job.

Those people on the far far away lands don't have any carpentery training and do whatever they feel like to meet the description of what they are supposed to deliver back.

While the carpenter tries to rescue what is possible from each delivery, so that the table and chairs only look half as bad, people can still seat on them without falling, and the tables have four legs about the same size.

This is a very concise description of a lot of modern manufacturing.

I just took apart a bunch of stuff on a VW van: the bus itself was nominally manufactured in Poland. According to some of the labels the guts of the servo that I took apart and repaired was made in Switzerland. But the servo itself was made in Germany. When you look at the guts parts of it were made in China, parts in Japan and probably some parts in Switzerland but it's unclear which those would be.

The parts of that car have collectively already traveled more than the car ever will by the time it gets delivered to the customer (in the Netherlands).

Indeed, it is everywhere.

> I’ve come to understand that most people won’t ever really appreciate it for the effort you put in.

I've had several people comment on the quality of my code. For a FOSS project. Of a command-line tool that nobody cares about.

People notice.

But yeah, this article is too much fluff because people don't see it that way.

Half of the people who commented on my code mentioned the snarky comments I wrote.

A study apparently found that open-source code with profanity in the comments was statistically measured to be of higher quality.

https://blog.desdelinux.net/en/el-open-source-con-malas-pala....

Discussed on HN 17 days ago [1]

As said there, this might as well be simply a correlation with commented code.

Or, people swearing might be an indication of having taste.

[1] https://news.ycombinator.com/item?id=36584464

I don't swear, so this is my replacement.

Let's share our gratitude indeed; it's like a warming fire.

I have had extraordinary coworkers who wrote incredibly solid code that was a joy to work with at every turn. When some of those coworkers have moved on, I've bought them thank you presents and taken them out for a meal to say thank you for making a difference. It's a token gesture in the face of how much I've learned from them and their wonderful work.

My message is to all of us who work away in the trenches of our day-to-day, where we stare through straws and move grains of sand; please let us shout and celebrate the granules of gold that our peers produce!

Most people might not appreciate "good code" but they'll sure as hell un-appreciate bad, unreadable code.

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.

It takes a master to recognize a master's work. Know that you have made their work easy even if they don't realize it.

> I don’t think I’d do much differently in retrospect, except be far more cautious about where and who I spend time around.

Another angle here is that code has become seen as something with the shelf life of a banana. People today talk of code merely a year old as legacy that needs to be rewritten ASAP. If one grew up in a world where code is scheduled to be thrown away as soon as it gets to production, I guess I can see how quality of code and documentation doesn't matter at all.

That's not a happy world though.

I grew up with the codebases of Unix (particularly SunOS, later Solaris). Code lives on for decades. One matures it to perfection and then it's perfect for a long, long time. That's a much more pleasant way to honor the craft.

I too have met many developers who have developed the mindset that good code is impossible. That is really sad.

Imagine a carpenter that says straight cuts aren't possible, just because they never maintained their tools and the last 10 cuts came out wrong.

Of course good code is possible. But not every person is going to write it and it is not going to happen under all possible circumstances and in all given project structures.

Seems like a duplicate to which my reply is here: https://news.ycombinator.com/item?id=36811381#36811433

"Imagine a carpenter that says straight cuts aren't possible, just because they never maintained their tools and the last 10 cuts came out wrong."

Anyone who's worked on a construction site would agree that this is not too far from reality.

I agree, it's quite sad, but that sentiment usually comes with burnout from too many quick deadlines and vast piles of tech debt.

> but that sentiment usually comes with burnout from too many quick deadlines and vast piles of tech debt.

That would be my question. We are not talking about people saying that within their context good code is not possible, we are talking about people who say good code is not possible, period. Maybe burnout has to do with it, maybe also depression. But I even if I was stuck in a job that made me churn put half broken code all day I'd still remember my hobby projects in which I experienced myself that perfectly fine code can be written by a single determined person — and quite frankly: it doesn't even have ro take that much longer, it just has to be a trusted, concentrated low pressure environment.

Agreed. At the same time, my customers are downright joyous when the code works and solves their problems. I've had numerous occasions where people were thrilled to meet me and gave me more hugs and praise than I was comfortable with once they heard that I created certain tools they use.

So while I do try to write good code, if you are looking for appreciation, it comes from what the code does, not how it is written.

other colleagues not caring is one thing, your company not recognizing the value and giving you the adequate compensation is another.. I don't mind if colleagues don't appreciate as long as I don't have to either lower my skills or be underpaid

I interned somewhere where I wrote a 56k modem codec decoder. That particular codec relies on decompression by streaming bits out, which is something awful. Was able to deliver it by summer’s end.

After I graduated college in 2004, they hired me at 50k.

I didn’t know my value.

> I didn’t know my value.

which is one the important point yet a very difficult information to get

what is mind blowing is how ignorant but somehow subconsciously proud (dunnig-kruger kind of way) will bully themselves into higher salaries (I've seen them repeatedly) while the good working, caring craftman will not and stagnate at lower pay.

worst of all is when the low skill guy becomes your boss..

Reply on news.ycombinator.com