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

241–250 of 647 posts

Re: Please do not attempt to simplify this code

#241

Post by tengbretson »

bdibs wrote: post #10
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.

I actually would say it’s almost the opposite, if you’re writing clean, expressive code it shouldn’t need explaining. And if your code is clean, you shouldn’t have a bunch of redundant comments explaining the obvious.

Precisely. I tend to only write comments that explain reasons for making non-idiomatic decisions like:

// It might look like you should do X here but esoteric reason Y dictates that you should do this instead.

Re: Please do not attempt to simplify this code

#242

Post by tengbretson »

tuananh wrote: post #238
bdibs wrote: post #125

Earlier quoted context omitted.

My comment was directed to the OP's question of comment:code ratio in general, not in this exact circumstance. Additionally, in no way am I advocating for no comments, that's obviously not possible (like your example). Comments are useful, even necessary, for code that might have an otherwise confusing logic to them. I've seen plenty of code with documentation for a method with nothing more than: /** * Bills the user…

no, in case like this, it's mostly for documentation generation. though you may find it useless.

Worse than useless. It harms your ability to take in multiple things at once on your screen.

Re: Please do not attempt to simplify this code

#243

Post by nailer »

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…

How long does it take you to write a sentence?

Re: Please do not attempt to simplify this code

#244

Post by ryanwaggoner »

coldtea wrote: post #119
TeMPOraL wrote: post #111

Earlier quoted context omitted.

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

> People like this, even if many don't want to admit it to others (or themselves) People only like the cheapness and the convenience (and perhaps the no-surprise factor). Everything else being the same (price and time to prepare), nobody would eat McDonalds vs a quality burger (except the kind of people who eat Hot Pockets for the taste, but that's a much smaller demographic than McDonalds buyers).

Disagree. I’m not a hardcore foodie, but I enjoy the entire spectrum of food, from fast-food to food trucks to homemade to Michelin 3-star restaurants. And sometimes I want Taco Bell, or yes, even McDonalds.

Re: Please do not attempt to simplify this code

#245

Post by tengbretson »

macintux wrote: post #43
josteink wrote: post #35

Earlier quoted context omitted.

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

Short functions help here. If every function is just a few lines long, the comments are easier to keep synchronized, and if a function drops out of service, it should eventually be garbage collected with its now-irrelevant comments.

If a function is only a few lines long its action should be entirely documented by its name.

Re: Please do not attempt to simplify this code

#246

Post by YorkianTones »

sridca wrote: post #212
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.

This. Documentation (comment blocks in code, as well as all other forms of documentation) tends to become outdated because it is not maintained in sync with every code change.

Solution: write clear, simple, modular code that is self-documenting and does not need extensive commenting.

Re: Please do not attempt to simplify this code

#247

Post by contingencies »

mlindner wrote: post #200

Why are people praising this monstrosity? Crazy complex non-simplifiable code is not good.

Yeah, 500+ upvotes on HN apparently think otherwise, but I also dare to disagree... it's not clear, despite claims to the contrary.

Comprehending this code relies on reading a long series of verbosely referenced assumptions around an implicit state machine with numerous error conditions and edge cases. The author's argument is that extreme verbosity in control structures assists with ensuring no such conditions escape an explicit code block - ie. they admit that they are (ab)using code to deal with their personal challenge of achieving a rigorous and precise conception of the problem. I would posit that approach is the wrong tool for the job, and further that they have simply failed to clearly articulate the problem, and are writing illegible code and documentation as a result. A clear symptom of the resulting fragility is the title / opening plea to others not to change their carefully constructed house of cards. Fragility does not good code make.

If I were to rewrite this, the implicit state machine and its valid transitions would be documented first and foremost, eg. with a railroad diagram or ABNF.

The benefit of using [a formal specification language] is that it teaches you to think rigorously, to think precisely, and the important point is the precise thinking. So what you need to avoid at all costs is any language that's all syntax and no semantics. - Leslie Lamport ... via http://github.com/globalcitizen/taoup

Re: Please do not attempt to simplify this code

#248

Post by gtrubetskoy »

apo wrote: post #236

One simplification that might be tempting is to replace the "if !condition" with "if condition". For example, line 463 shows: if !found { // handle missing } else { // handle found } I would simplify this to: if found { // handle found } else { // handle not found } Or even: if missing { // handle missing } else { // handle not missing } The test-negative style is repeated throughout the file, but inconsistently. Som…

My guess is that this is in line with the Go tradition of first handling all the odd cases leaving the essential part of what the function (or block of code in this case) attempts to do as the last part. So "if !found" to me suggests that this is more of an exception than the rule and this is why the code is written so as to deal with it first.

Re: Please do not attempt to simplify this code

#249

Post by vharuck »

nerdponx wrote: post #19
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.

Knuth allegedly attributes the stability of TeX to his literate programming style.

I was reminded of Knuth, too. The code/comment blend encourages reading it like a white paper.
Post reply on HN