Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

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

addyosmani.com

Post reply on HN
Print view View original

241–250 of 274 posts

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

#241

Post by majikandy »

Mawr wrote: post #204
majikandy wrote: post #64

Earlier quoted context omitted.

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.

I’m just suggesting that the comments are the last resort, the same as you say there. For me, the test names cover the why.

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

#242

Post by majikandy »

jedberg wrote: post #80
majikandy wrote: post #64

Earlier quoted context omitted.

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.

I'm a big fan of self documenting code, but especially when I'm doing quick and dirty projects for myself, where I value speed and cleverness over correctness, the comments really help. Especially when it comes to explaining past me's cleverness.

Yes I was only really referencing production long lived code. Mostly I’m a big fan of quick and dirty being something that doesn’t really exist. I believe in quick and throwaway and quick and single/multi use. Comments are fine, just the original suggestion I was referencing sounded like they were a priority.

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

#243

Post by dack »

andelink wrote: post #232
CodeyWhizzBang wrote: post #213

Earlier quoted context omitted.

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.

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

#244

Post by randomNumber7 »

crucialfelix wrote: post #164
ugh123 wrote: post #50

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…

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.

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.

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

#245

Post by danbruc »

wouldbecouldbe wrote: post #239
danbruc wrote: post #210

Earlier quoted context omitted.

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?

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.

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

#246

Post by npteljes »

majikandy wrote: post #64
jedberg wrote: post #40

Earlier 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.

>A good alternative is code without comments that communicates just as well as that code without the comments.

Now this is something I could never do. Or find in other people's code. I much rather appreciate the good comment explaining to me WTF is going on, annotating the larger segments, and so on. Of course it might just be my personal limitation as a programmer that's far from the best in the craft. But to me, comments are the most time tested.

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

#247

Post by imoverclocked »

mattgreenrocks wrote: post #111
imoverclocked wrote: post #57

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 ext…

If there is no such thing as good code, why does it spark so much discussion? Why care at all?

We can all be passionate about what we care about and strive to be better. For me, this is what looking back at my old code means. When I see that I could have done something better, it means that I have grown. It also means that whatever I produce now could probably be improved upon. The biggest trap (for me) in this endeavor is to not be a perfectionist; One can spend a lifetime improving/optimizing/refactoring/etc. By accepting that there is no single encompassing definition of "good code," I am freed to choose the attributes that I think matter most for a particular piece of code.

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

#248

Post by jedberg »

majikandy wrote: post #241
Mawr wrote: post #204

Earlier quoted context omitted.

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.

I’m just suggesting that the comments are the last resort, the same as you say there. For me, the test names cover the why.

What tests?

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

#249

Post by bccdee »

majikandy wrote: post #64
jedberg wrote: post #40

Earlier 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.

"A good alternative to a car with seat belts is a car without seat belts that is nevertheless equally safe."

There's lots of important information that comments can convey which code itself cannot. In particular, a program's code can tell you how it works but not why it was designed to work that way.

And after a point, even trying to convey too much information about how a program works through code can be cumbersome. We've all seen function names that are way too long, because the author wanted to cram way too much information into it. That extra information should have been put into a comment, where the author could have articulated it clearly, instead of as a single overlong compound verb in camel case.

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

#250

Post by andelink »

dack wrote: post #243
andelink wrote: post #232

Earlier quoted context omitted.

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…

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.
Post reply on HN