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

Please do not attempt to simplify this code

github.com

Post reply on HN
Print view View original

131–140 of 647 posts

Re: Please do not attempt to simplify this code

#131

Post by geofft »

Karrot_Kream wrote: post #86
startupdiscuss wrote: post #3

The comment:code ratio is higher than anything I write or that I’ve seen. However, it does give me some comfort. When it’s not gamed, do other HNers also feel that a high comment:code ratio probably indicates quality? There are reasons why this may be the case. (More thought, more time and a large team etc) I don’t advocate using this measure to reward anyone because it would be gamed immediately.

There's a lot of talk about comments becoming stale and code being self documenting in the replies which makes me wonder: do people genuinely not read comments and just made code changes without updating comments? And do reviewers not look at the context of the surrounding code and just let commits in? What's the point of having code reviews then?

Comments straddle this weird line between code and human process. They're in the source code files themselves, and there is an appeal to trying to evaluate a project by looking at the source code alone and trying to gauge abstract technical merit. But I think the real truth here is that comments are a tool in the service of a development process, which includes things like having code reviews, having code reviewers be sufficiently motivated (intrinsically or extrinsically) to care in useful ways and neither nitpicking nor rubber-stamping, having motivated people on the project in the first place, having shared values about what code you're going to write and what code you're not, having tests and doing the operational work to keep tests running, retaining people on the team, etc.

Re: Please do not attempt to simplify this code

#132

Post by bb88 »

iamwil wrote: post #104
endymi0n wrote: post #50

Earlier quoted context omitted.

I know a business coach who regularly asks his audience "Who here makes better burgers than McDonalds?". When half the audience raises their hand, he asks them why they don't outsell this giant company. Functional programming advocats, especially for the "pure" ones like Haskell, always strike me as odd. It seems that all the beauty of those languages make people obsess over that beauty and purity while keeping them…

Selling a lot of burgers encompasses much more than making good burgers. By the same token, good products entails much more than making a programming language choice. Functional programming, at its heart, is about using self-imposed constraints to avoid certain classes of programming mistakes. If your application domain doesn't have big consequences for these classes of programming mistakes, then it can seem like fun…

> So yes, just because you use a functional programming language won't help you sell your widgets or make a great product. And you can spend lots of time fucking around with it for its own sake and still not sell widgets or make a great product.

It comes down to trust. You're either fucking with your code in a powerful programming language that lets you do everything, or your fucking with the language restrictions to get your code to compile in the first place.

You can either go eat at McD's which sells pre-cooked burgers from minimum wage employees which kills the flavor and the taste of the meat being served but is extremely safe, or you can go to an upscale burger joint where artisans grind their meat in house and cook it to a perfect medium rare.

These days, I prefer the latter.

Re: Please do not attempt to simplify this code

#133

Post by franciscop »

On a related note, please note that most people have the opposite issue, myself included. I know we are highly biased and tend to overcomplicate things, so I follow the KISS rule by heart.

But when I do have to write complex parts of software that cannot be simplified, I will take a lot longer because I'll need to prove, first to myself, that it really cannot be simplified. Then I'll still add a big warning, either to others or to my future self (which is effectively a different person).

Re: Please do not attempt to simplify this code

#134

Post by iseeyoubydesign »

Klathmon wrote: post #21

I love this! It's the "jazz music" of software development. Something which breaks all the "rules" but does so purposefully and explicitly so that it can become better than the "rules" allow. A naive look at this and my head is screaming that this file is way too big, has way too many branches and nested if statements, has a lot of "pointless comments" that just describe what the line or few lines around it is doing,…

oh no the "I love it" first post ... the fact this type of post is the top of so many threads leads me to believe theres more behind these posts.

the positive renforcement cheerleading to start off so that people dont get demoralized in the hateful comments, while effective also seems fake.

Re: Please do not attempt to simplify this code

#135

Post by chrisweekly »

EB66 wrote: post #91
Klathmon wrote: post #21

I love this! It's the "jazz music" of software development. Something which breaks all the "rules" but does so purposefully and explicitly so that it can become better than the "rules" allow. A naive look at this and my head is screaming that this file is way too big, has way too many branches and nested if statements, has a lot of "pointless comments" that just describe what the line or few lines around it is doing,…

I completely agree. For code that is unavoidably complex, I love this style too. I am all for code that is concise and whose syntax/naming is expressive, but sometimes comments are necessary to clearly spell out the logic or business use case. Expressive code can only go so far. Well-crafted comments significantly reduce the amount of time required for other developers to dive in and become productive with an unfamil…

Agreed. Also, comments that emphasize the "why" over the "what" are not obviated by descriptive names.

Re: Please do not attempt to simplify this code

#136

Post by lazyjones »

josteink wrote: post #35
startupdiscuss wrote: post #3

The comment:code ratio is higher than anything I write or that I’ve seen. However, it does give me some comfort. When it’s not gamed, do other HNers also feel that a high comment:code ratio probably indicates quality? There are reasons why this may be the case. (More thought, more time and a large team etc) I don’t advocate using this measure to reward anyone because it would be gamed immediately.

> do other HNers also feel that a high comment:code ratio probably indicates quality? I consider it a big risk of errors. When some code is changed, will all related comments be rewritten too? I doubt it. And then you end up with a codebase which indicate A but comments which clearly spell out B, and you as a maintainer have no idea what to believe. DRY. Don’t repeat yourself. The comments should not double up for th…

> And then you end up with a codebase which indicate A but comments which clearly spell out B, and you as a maintainer have no idea what to believe.

Can you name a few examples where you encountered this? In my career (30 years programming) I've never seen it. I believe it's a common, poor excuse for not writing enough comments.

The benefits of comments are well-understood. For me personally they often helped compensate sloppy code, (non-obvious) assumptions and prevented bad solutions because I reconsidered while writing (embarrassing) comments.

when you have to maintain a large codebase modified thousands of times in 15+ years, every single comment is invaluable.

Re: Please do not attempt to simplify this code

#137

Post by simplyluke »

TeMPOraL wrote: post #123
twunde wrote: post #64

Earlier quoted context omitted.

It's really only useful in areas of codebases that either a) are very complex, b) touched by many people or c) both. When that happens, everyone prefers that there is a lot of documentation, especially about the why. With older codebases the question is always whether this is an actual bug from the developer or is there a reason why it's doing this super-weird thing and if so is it still applicable. What's happened o…

You've missed d) the codebase lives longer than a few months and someone else than the original author has to make changes. Comments describing the intent and caveats are extremely useful in ensuring the future developer gets adequate understanding quickly, and reduces the chance they'll introduce bugs. Tests can help understand the interface, but they don't help to understand the rationale behind it, the underlying…

Agree 100%, along with accompanying documentation that lays out architecture, rationale, challenges, etc. All of those are invaluable for any code that will outlive the tenure of the developers who built it. And given how often people in tech change jobs that's virtually all code.

Re: Please do not attempt to simplify this code

#138

Post by TeMPOraL »

Karrot_Kream wrote: post #86
startupdiscuss wrote: post #3

The comment:code ratio is higher than anything I write or that I’ve seen. However, it does give me some comfort. When it’s not gamed, do other HNers also feel that a high comment:code ratio probably indicates quality? There are reasons why this may be the case. (More thought, more time and a large team etc) I don’t advocate using this measure to reward anyone because it would be gamed immediately.

There's a lot of talk about comments becoming stale and code being self documenting in the replies which makes me wonder: do people genuinely not read comments and just made code changes without updating comments? And do reviewers not look at the context of the surrounding code and just let commits in? What's the point of having code reviews then?

I'd say it's mostly a meme. If a code review doesn't involve reviewing comments around the modified code, it's a bug in the process.

Elsewhere in this thread Ousterhout's book is mentioned; I like his advice about always placing comments in the most obvious places and as close to the code they affect as possible. This way, you can't miss them, and and it's hard to forget to update them.

Re: Please do not attempt to simplify this code

#139

Post by yen223 »

Karrot_Kream wrote: post #86
startupdiscuss wrote: post #3

The comment:code ratio is higher than anything I write or that I’ve seen. However, it does give me some comfort. When it’s not gamed, do other HNers also feel that a high comment:code ratio probably indicates quality? There are reasons why this may be the case. (More thought, more time and a large team etc) I don’t advocate using this measure to reward anyone because it would be gamed immediately.

There's a lot of talk about comments becoming stale and code being self documenting in the replies which makes me wonder: do people genuinely not read comments and just made code changes without updating comments? And do reviewers not look at the context of the surrounding code and just let commits in? What's the point of having code reviews then?

It's very easy to miss comments, since they aren't type-checked, nor are they unit-testable.

Comments don't need to be near the code they affect. They don't even need to be in the same file - consider if you've organized your code by features, but the comment relates to a layer than spans multiple features.

Re: Please do not attempt to simplify this code

#140

Post by _ph_ »

As much as I like the style where the code logic is commented very thoroughly, it also falls in the trap of comments no longer matching the current code, I assume some variable renaming happened. In the function (line 320 of https://github.com/kubernetes/kubernetes/blob/ec2e767e593953...)

   func (ctrl *PersistentVolumeController) syncUnboundClaim(claim *v1.PersistentVolumeClaim) error {
the variable "pvc" seems to have been renamed into "claim" and "pv" into "volume", judging from the code/comment mismatch. Comments in the lines 339, 358, 360, 370, 380, 395, 411, 422, 427 point to the old names. Furthermore in line 370 the comment reads:

   } else /* pvc.Spec.VolumeName != nil */ {
while the matching if is:

  if claim.Spec.VolumeName == "" {
So not only the variable name mismatches, but also the comment is wrong. The VolumeName seems to be a string, so is never nil, the else comment should specify that the VolumeName is non-empty.

The more verbose and detailled the comments are - the more work needs to be spent in ensuring that they are correct.

Post reply on HN