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

621–630 of 647 posts

Re: Please do not attempt to simplify this code

#621

Post by lazyjones »

tigershark wrote: post #229
lazyjones wrote: post #136

Earlier quoted context omitted.

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

Then you must have been very lucky, I have seen it happening probably hundreds of times in a mere 15 years on the job. The inconsistencies that I experienced ranged from doc strings stating to pass a parameter that didn’t exist any more, parameters with different names, parameters with the correct names but in different orders. As per actual comment I have seen plenty of time comments like //here we go baby! //do not…

I was asking specifically about comments that directly contradict the code in a way that confuses the reader. If obsolete comments like "never delete" stand before commented code, what makes you think the commented code is actually used or useful?

> “(non-obvious) assumptions” - this is probably the only legitimate reason to write a comment.

If that's what you think, I rest my case...

Re: Please do not attempt to simplify this code

#622

Post by pas »

dwild wrote: post #560
pas wrote: post #489

Earlier quoted context omitted.

I vehemently disagree. Code without specification is a maintenance nightmare, a pure liability, a ticking time bomb. And sure, unless you're creating the control system of a nuclear reactor/warhead you don't have to go full Coq and CMMI5 and "high assurance" and whatnot, but spilling a few sentences as a minimal kind of pseudocode before writing what you want (a function, a class, a method, change the build system, r…

Personally I consider that if the code don't speak for itself, then it's most probably bad code, if it's not, add a comments explaining why it's not. > spilling a few sentences as a minimal kind of pseudocode before writing what you want Isn't it simply repeating the code you'll write? Which in the end, will be just as bad as the code alone or will lose time of the one that will read it afterward. Sure it's hard to w…

Code cannot explain the engineering constraints, the business orientation, the goals. Ie. it must work in IE10 so we use this or that.

Re: Please do not attempt to simplify this code

#623

Post by james_s_tayler »

nailer wrote: post #618
james_s_tayler wrote: post #601

Earlier quoted context omitted.

Well people keep picking arbitrary starting points in the coordinate system. I'm saying for any arbitrarily picked starting point in the coordinate system, the time taken is always twice that of getting from the arbitrarily picked starting point to the halfway mark. A tautology is a tautology. How long is a piece of string?

You're not a very effective communicator.

I'm glad we're on the same page.

Re: Please do not attempt to simplify this code

#624

Post by weberc2 »

bb88 wrote: post #613
weberc2 wrote: post #580

Earlier quoted context omitted.

Sure, but I doubt all of Kubernetes is written in this style, so it’s probably not worth writing everything in Haskell. Note also that there’s nothing about FP that prohibits it from addressing the aforementioned practical problems. Some Haskell-like could swoop in and totally steal Go’s lunch if they would simply prioritize practicality over experimentation.

> Some Haskell-like could swoop in and totally steal Go’s lunch if they would simply prioritize practicality over experimentation. I don't know. It seems like it would be easy enough to build an AST to make sure there were no unknown conditions that didn't lead to a return statement.

I don’t understand how your post relates to mine. I was saying that if a static functional language focused more on simplicity, readability, good tooling and documentation, etc then it would eat Go’s lunch without trading off any of Haskell’s important characteristics (I.e., robust type safety).

Re: Please do not attempt to simplify this code

#625

Post by [deleted] »

iainmerrick wrote: post #117

This looks like pretty normal code. What is all the “space shuttle” stuff about? The only unusual things I see are a) 8-space indentation, b) lots of “if err { return nil }”, and c) lots of comments. Aren’t a) and b) standard for Go? How else is it possible to write Go code? With less verbose error handling and 2- or 4- space indentation it wouldn’t look especially “branchy”.

[deleted]

Re: Please do not attempt to simplify this code

#626

Post by sbr464 »

iainmerrick wrote: post #117

This looks like pretty normal code. What is all the “space shuttle” stuff about? The only unusual things I see are a) 8-space indentation, b) lots of “if err { return nil }”, and c) lots of comments. Aren’t a) and b) standard for Go? How else is it possible to write Go code? With less verbose error handling and 2- or 4- space indentation it wouldn’t look especially “branchy”.

Add ?ts=2 to the url on github, it will lower the tab width.

Re: Please do not attempt to simplify this code

#627

Post by pas »

xixixao wrote: post #494
lmm wrote: post #451

Earlier quoted context omitted.

> There are those that believe good code shouldn't need explanation and to some degree that's true, but you can't apply that brush to every codebase. Code can become complex, awkward, spaghetti-like and almost unfathomable at times. I have yet to find a codebase that couldn't be made clear as soon as a programmer actually put some effort into doing so. Far too often adding a comment is used as an excuse to give up on…

Here’s a great practice: 1. Write some piece of code 2. Now write a comment about it 3. Is the comment adding more information, making the code more clear? If Yes: Put that information into the code. Rename variables. Pull out code into subroutines. If No: Delete the comment. You’ll be amazed at how often this practice works. Doing it all the time will make your code more readable. We have a second, enforced practice…

There are concerns and aspects of software engineering that are important to document but don't sit well in code, but they become important when reading / maintaining that code. Design decisions (implementation details), specification details, other design or engineering constraints. And of course business modeling fundamentals and constraints.

Sure, in theory, you can do everything in code, but I find that usually this trade off is taken, as there's no time/budget to go that 80% extra time. (Or however the Pareto curve looks for the actual problem. And usually it's not less than 80, but more.)

Re: Please do not attempt to simplify this code

#628

Post by pas »

lmm wrote: post #451
nickharr wrote: post #224

Having spent 25+ years writing, viewing, commenting on and reviewing code in a multitude of languages, this is good stuff to see - regardless of the 'style' of programming (or the language broadly-speaking). Stepping back and whilst we can all overlook it, good code comments can make an enormous difference in productivity - both for an individual, a team and indeed a business. It aids repository knowledge (something…

> There are those that believe good code shouldn't need explanation and to some degree that's true, but you can't apply that brush to every codebase. Code can become complex, awkward, spaghetti-like and almost unfathomable at times. I have yet to find a codebase that couldn't be made clear as soon as a programmer actually put some effort into doing so. Far too often adding a comment is used as an excuse to give up on…

Well, you seem to be providing data against your own theory.

Usually codebases are a mess, so were people commenting more on what's the goal then refactoring it would be easier.

Software is very susceptible to the "perfect is the enemy of done" mantra. Software works as soon as it works for the first time. And then it gets a shipped. It's 1.0, even if it looks like a mess internally. Because IT development is expensive, there is rarely budget to go that extra mile (which is again usually would cost a lot more than the first few miles).

Re: Please do not attempt to simplify this code

#629

Post by pas »

majikandy wrote: post #617
kyberias wrote: post #614

Earlier quoted context omitted.

I think you're giving very bad advice. > On a basic level, comments should: inform, educate, outline and help others understand the sometimes complex routines and functions that we all create and often under an enormous amount of pressure. Take the time to simplify the complex routines, clean them up and make them readable and don't waste your precious time in writing "good comments". > Code can become complex, awkwa…

Well said, I was cringing when I was reading the bad advice and you addressed the points very well. It is so frustrating to hear when someone thinks commenting more and adding humour is somehow cleaning up the code. But to then hear that they are teaching this to juniors just hurts so much. Simpler advice to juniors would be to read Clean Code by Robert C Martin, apply some of those techniques and then politely ignor…

I disagree with nickharr's opinion on humor just as starkly as you, but agree with the need for comments very much. And his/her point still stands regardless of how much you name and group functions. There are concerns and aspects (design/engineering decisions become implementation details that might need rationale) that can't be presented efficiently that way. (Workarounds for issues benefit a lot from links to the relevant issue trackers, and so on.)

Re: Please do not attempt to simplify this code

#630

Post by pas »

kyberias wrote: post #615
asadkn wrote: post #541

Earlier quoted context omitted.

Agreed. One of my pet peeves is JS projects. I am not sure why but the front-end developers refuse to add any comments at all. This trend, oddly enough, started with ES6. Pre-ES6, JSDoc style comments at least, were quite common. Just because some popular Javascript project doesn't have comments doesn't mean yours shouldn't. Straight-forward code may not need comments but most of these projects definitely need to exp…

> Straight-forward code may not need comments but most of these projects definitely need to explain why or how are things supposed to work or why things are done a certain way. Code comments usually are not the best place to elaborate on "why things are done a certain way". One can also write documentation about the architecture, design etc.

That'd be great, but rarely done. And usually there's a big impedance mismatch between the design document's level of detail and the level that'd be actually useful were someone trying to understand the actual code. (Hence comments seem to me to be the ideal place for documentation. Especially that they can be maintained right at the time the code changes.)
Post reply on HN