Please do not attempt to simplify this code • Hacker News Board

Re: Please do not attempt to simplify this code

#211

Post by chris_wot » Fri, Dec 28, 2018, 12:45 AM UTC

ascar wrote: post #158

EB66 wrote: post #91

Earlier quoted context omitted.

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…

Outdated comments that explain the business use case or purpose are still better than no comments. It gives you background information how the code evolved or what it was supposed to do. It's probably because reading comments only is worse than reading code without comments, that some devs developed an aversion towards outdated comments and thus comments in general. Comments are additional information and no source o…

It’s much worse in codebases that predate version control. At least a commit shows the context of why it was added.

Re: Please do not attempt to simplify this code

#212

Post by sridca » Fri, Dec 28, 2018, 12:47 AM UTC

pdkl95 wrote: post #110

Ignoring the initial boilerplate (license, imports) and the request to preserve the verbose ("space shuttle") style, the first line is: // Design: // // [... 4 paragraphs of English prose // explaining goals and intent... ] That's exactly the type of comment that should be at the beginning of most files!

Yea, but watch how soon it becomes outdated as the file changes.

Re: Please do not attempt to simplify this code

#213

Post by ElijahLynn » Fri, Dec 28, 2018, 12:50 AM UTC

pdkl95 wrote: post #110

Ignoring the initial boilerplate (license, imports) and the request to preserve the verbose ("space shuttle") style, the first line is: // Design: // // [... 4 paragraphs of English prose // explaining goals and intent... ] That's exactly the type of comment that should be at the beginning of most files!

One thing that I wish Linux kernel code had. Maybe it does but the few times I have found myself reading Linux code I go to the top and there is zero context in the comments, just a bunch of licensing information.

Re: Please do not attempt to simplify this code

#214

Post by zeroimpl » Fri, Dec 28, 2018, 12:53 AM UTC

adjkant wrote: post #175

jml7c5 wrote: post #165

Earlier quoted context omitted.

As a novice programmer, I was absolutely stunned that this was not standard practice. A typical source file provides zero context, background on the subject, pointers to reference material/blog posts/books explaining the concepts, information on how it fits into the program's 'bigger picture', or (most importantly) the thought process that resulted in the file (i.e., why the choice was made to do _this_ rather than _…

I think your desire is right, but think about this every time you create a file, and how much slower your work would be. The question then becomes: "how much commenting exactly is needed before this becomes more time than the technical debt it creates? I think this type of summary should not be per source file but per package/folder/module/project. A high-level developer overview with sufficient depth will also help…

I think this commenting only makes sense if the design is atypical. Probably 90% of the code I write is following design patterns already used throughout the code base.

Re: Please do not attempt to simplify this code

#215

Post by slumos » Fri, Dec 28, 2018, 12:55 AM UTC

germainelong wrote: post #63

The comment claim that every branch is accounted for and yet few functions below you can see this is certainly not the case. They should either have fixed it first and then make such comment or shouldn't make such comment at all. Otherwise this looks a bit cringey.

This. It’s the second function in the file.

Re: Please do not attempt to simplify this code

#216

Post by FPGAhacker » Fri, Dec 28, 2018, 12:56 AM UTC

lewisf wrote: post #205

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…

Seems like you have bad experiences with functional programming, but it's a little strange to rat on the advocates that are trying to figure out how to take potentially useful functional programming concepts and make them mainstream and/or explore alternative ways to quickly build robust systems. Good examples of this translating to huge gains for the overall community are React + Redux. I'm quick to admit that funct…

A lot of things seem to get lumped into “functional” programming. The lexicon changes so I may just be behind the times, but ensuring every condition of branch logic is covered is not an aspect of functional programming as I understand it. And I may be wrong.

Re: Please do not attempt to simplify this code

#217

Post by nradov » Fri, Dec 28, 2018, 12:57 AM UTC

For background on how actual Space Shuttle flight control software was written I recommend reading the "NASA Manager's Handbook for Software Development". It contains some great guidelines for writing safety-critical software. AFAIK, no Space Shuttle mission ever suffered a serious safety incident due to a software defect.

https://ntrs.nasa.gov/search.jsp?R=19910006460

Re: Please do not attempt to simplify this code

#218

Post by Dylan16807 » Fri, Dec 28, 2018, 12:57 AM UTC

TeMPOraL wrote: post #111

the_af wrote: post #98

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. There is indeed a lesson here, but which one do you think it is? It's certainly not that McDonald's makes better (or "simpler") hamburgers: once you taste good hamburgers you can never go back to McDonald's (and yes…

> It's certainly not that McDonald's makes better (or "simpler") hamburgers At the risk of derailing the thread, that would be the lesson I wish people would take away from that example. Criticizing fast food like that is dumb signalling IMO; McDonald's!hamburger != homemade!hamburger. It's an entirely different product sharing the same name and some of the ingredients. It tastes different, and has a different form f…

Plenty of places can get me a significantly better burger in under a minute. McDonald's is not high up inside its category.

Re: Please do not attempt to simplify this code

#219

Post by busterarm » Fri, Dec 28, 2018, 1:04 AM UTC

dkarl wrote: post #180

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

About five years ago I worked on a codebase with a similar bit of code. It wasn't nearly this big, but it was branchy, procedural, and verbosely commented. I didn't write the initial version but worked on it quite a bit and learned to appreciate the advantages of the style for the nasty bit of logic it implemented. I ended up having to vigorously defend it against another developer's half-cocked attempt at "refactori…

Honestly, after the experience described, I would consider the person a work hazard and try to make sure they didn't touch anything business critical.

Re: Please do not attempt to simplify this code

#220

Post by nerflad » Fri, Dec 28, 2018, 1:05 AM UTC

qlk1123 wrote: post #204

jml7c5 wrote: post #165

Earlier quoted context omitted.

As a novice programmer, I was absolutely stunned that this was not standard practice. A typical source file provides zero context, background on the subject, pointers to reference material/blog posts/books explaining the concepts, information on how it fits into the program's 'bigger picture', or (most importantly) the thought process that resulted in the file (i.e., why the choice was made to do _this_ rather than _…

> As a novice programmer, I was absolutely stunned that this was not standard practice. I agree with your point, and I will be benefit from this style if it were the standard, too. But don't you think a good community culture can make people maintain a good git history for this purpose? My daily job is a Linux kernel developer. I found that source codes are only the "What" part, git comments can and should state the…

Not all organizations have such robust communication structures, low levels of dysfunction, or git hygiene. Also, as mentioned, in a corporate environment where the software is proprietary and certain source files may sit dormant long enough for the original authors to move on from the company, it's important that they don't take the "how/why" part with them, so to speak, and leave the next maintainer SOL.