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

Code only says what it does

brooker.co.za

Post reply on HN
Print view View original

81–90 of 120 posts

Re: Code only says what it does

#81

Post by webmaven »

xsmasher wrote: post #48
softwaredoug wrote: post #11

“works as coded” My last job we used to say that if asked whether our code was correct or bug free ;). Often the devs get thrown under the bus if something doesn’t work “correctly” when in reality it might perfectly pass all unit tests based on the best understanding of the problem. Of course whether we could get any support to help define “correct” from anyone was another matter...

This fits my theory of programming, and theory of bugs - We take a problem, create a plan, and then write code that implements that plan. Defects can come from: * having/being given the wrong problem * right problem, but plan does not actually solve it * right plan, but your code did not correctly implement it

Then of course there are the maddening cases of accidental correctness. ie. a bug in your implementation of the wrong plan does the right thing.

Re: Code only says what it does

#82

Post by smitty1e »

I'm looking at some ETL code from the dark past, and it uses low-level Db code to shovel in .csv files like a boss.

I'm all' "Well, I guess that code that obtains the .csv files must be rock solid."

Famous last words.

A freshly done system later, I'm left to infer that there had been some other cleansing to to which I was never privy.

Re: Code only says what it does

#83

Post by RandallBrown »

trixie_ wrote: post #70
tigershark wrote: post #54

Earlier quoted context omitted.

Clear code and clear tests absolutely don’t need comments that explain them if they are really clear, at least for me. Comments are extremely useful to explain something unexpected. Commit messages are too limited to explain properly a use case, but linking to a Jira with the proper explanation does the trick. From the tests you can see both the typical use cases and the correct way of using some piece of code and ha…

Right you are exactly the kind of person I'm talking about. You think your code is clear. It is not. The logic your code performs is the distilled by-product of higher level reasoning. Reasoning that should be the basis of your comments. People reading your code will not be in the same mind state that you were in when you wrote it. That is what the comments are meant to assist with. If you write comments for anyone,…

If someone's code isn't self explanatory from the naming and organization, why would you expect their comments to do a better job?

The vast majority of comments I see are completely useless, either giving incorrect/outdated information or restating exactly what the code says. I've even made comments nearly the same color as the background in my text editor so it's easier for my brain to skip them.

Comments certainly can be useful, but I think they should be used extremely sparingly.

Re: Code only says what it does

#84

Post by zimpenfish »

pronoiac wrote: post #30
ris wrote: post #24

So many times this. "Clear code shouldn't need comments" - clear code can make it easy to see what but it can never say why . Let me know what corner cases you thought about when you wrote this. "The comments are in the commit messages" - almost nobody ever goes looking for them there, they're effectively invisible from `git blame` when they remove lines, people rarely make fine grained enough commits to be able to t…

> "The comments are in the commit messages" - almost nobody ever goes looking for them there Consider it another tool in the toolbox. I've gone spelunking through git history to decipher the reasoning of something still in use, though comments had been deleted and no one had documented it before me.

This works iff there are good commit messages. In my experience, people who don't document their code tend not to bother with good commit messages either.

Re: Code only says what it does

#85

Post by ChrisMarshallNY »

thdrdt wrote: post #63
ris wrote: post #24

So many times this. "Clear code shouldn't need comments" - clear code can make it easy to see what but it can never say why . Let me know what corner cases you thought about when you wrote this. "The comments are in the commit messages" - almost nobody ever goes looking for them there, they're effectively invisible from `git blame` when they remove lines, people rarely make fine grained enough commits to be able to t…

The only time I place comments is exactly this: to explain why. Today I just had this example. I placed a little sleep in a loop. But there is absolutely no way to know why it is there. So I inserted a comment to explain the loop is DOSing a server by constantly requesting it and the sleep will reduce the load on that server. Those comments are not only for others but also for yourself. Even weeks from now it is easy…

That's exactly what I do.

Why is a lot more important that what.

Here's an example I use (Verbatim from here[0]):

-

Why Vs. What

I’ve come to realize that the most important inline documentation concerns WHY we are doing something; not WHAT we are doing. For example, no one wants to read “// Set the value of b to 3,” for a line of code that looks like let b = 3. That’s just dumb.

let b = 3 // Set the value of b to 3

However, they may want to know “// Set the value of b to the number of iterations we'll be making.”

let b = 3 // Set the value of b to the number of iterations we'll be making

-

[0] https://medium.com/chrismarshallny/leaving-a-legacy-1c2ddb0c...

Re: Code only says what it does

#86

Post by perl4ever »

thdrdt wrote: post #63
ris wrote: post #24

So many times this. "Clear code shouldn't need comments" - clear code can make it easy to see what but it can never say why . Let me know what corner cases you thought about when you wrote this. "The comments are in the commit messages" - almost nobody ever goes looking for them there, they're effectively invisible from `git blame` when they remove lines, people rarely make fine grained enough commits to be able to t…

The only time I place comments is exactly this: to explain why. Today I just had this example. I placed a little sleep in a loop. But there is absolutely no way to know why it is there. So I inserted a comment to explain the loop is DOSing a server by constantly requesting it and the sleep will reduce the load on that server. Those comments are not only for others but also for yourself. Even weeks from now it is easy…

Yeah, but the phrase "only time" somewhat suggests you use "why" as an excuse to comment rarely. You can nonetheless write such a comment for essentially every line.

My job description is not "developer" at the moment, so when I was asked to comment my code in order to turn it over to the developers, I looked for some standards. The document I found said, more or less, that you should write comments such that if the code was removed, someone could use the comments to completely reconstruct it.

An obvious problem is that you can write about the "why" of anything on a micro or macro level or in between.

Re: Code only says what it does

#87

Post by [deleted] »

ris wrote: post #24

So many times this. "Clear code shouldn't need comments" - clear code can make it easy to see what but it can never say why . Let me know what corner cases you thought about when you wrote this. "The comments are in the commit messages" - almost nobody ever goes looking for them there, they're effectively invisible from `git blame` when they remove lines, people rarely make fine grained enough commits to be able to t…

[deleted]

Re: Code only says what it does

#88

Post by blt »

aequitas wrote: post #59

My pathway into software development was through electrical engineering and embedded systems. So I don't know if this applies to other ways into software development as well. But what really stood out to me in the beginning was how useless code comment where. I would almost always see code like this: x = 1; // assign 1 to x y = x * 2; // multiply x by 2 I don't know if it was because they thought electrical engineers…

Those samples were probably written by someone who had learned how to code in assembly language. In assembly, this kind of comment reminds the reader of the semantic meaning of what is in each CPU register. It could be very useful. Then the person learns C and never drops this habit.

Re: Code only says what it does

#89

Post by hinkley »

Jtsummers wrote: post #75
hinkley wrote: post #69

Earlier quoted context omitted.

I think I have to disagree with Naur on this, in that people using the Scientific Method don't ship their theories, but we do. As a scientist who has just succeeded in testing a hypothesis, I now need to go back and document a simplified series of steps that should lead any independent party to the same phenomenon. Once we are on the same page, they can confirm or refute my theory based on their own perspectives on t…

I think I have to disagree with you on this one, I've used the scientific method (though not in an explicit checkbox-y way) plenty of times to ship and debug code. In particular, since (as I've said on this forum many times) I work primarily on the maintenance end of software. I don't know what the creators or previous developers were thinking, especially with more recent projects (documentation quality has really go…

I don't mean 'use' as in a #7 torx wrench. I mean 'use' as in air.

I have shipped bug fixes using organized hypothesis checking as well. Especially sanity checks (make sure the instruments are working). But it is not the software developer's default behavior, and I'm sure you've lamented it just as I have. You and I are tourists, and many around us aren't even that. So when we speak of whether 'we' apply formal rigor to our work? Is it still rigor when there is no discipline? I don't think rigor is something you do on a random Thursday. It's something you do all the time.

So no, 'we' do not use the scientific method. We dabble.

And so when someone like Naur tries to summarize software with a line about theory proving, he's not speaking about everybody. If he were honest he might not even be speaking accurately about himself.

ETA: But he's talking about the long arc, not a single bug fix. That we are circling in on what the actual problem is and feeling it out with code. But since we stop at "if it ain't broke don't fix it", we never actually crystallize the thing we built. We never test the hypothesis we suppose that we have created. We have spot checked this organic thing that never gets pinned down and might actually be DOA. We hope the evidence we are wrong is just 'glitches' or problems with the user's machine. Until someone comes to us with a counter-proof that shows unequivocally that we were wrong.

Which leads to problems like those mentioned in this comment tree.

Re: Code only says what it does

#90

Post by shepherdjerred »

phendrenad2 wrote: post #39
sanderjd wrote: post #28

Earlier quoted context omitted.

> almost nobody ever goes looking for them there I've seen this claim a number of times and it's always so odd to me. One of my most common activities each day - certainly more common than the activity of writing new code - is reading the commit history for different files. It's always surprising to me to hear that this is an uncommon thing to do. Edit to add: But I also think comments and documentation of all kinds…

Commit messages are much harder to get to for a given line of code than a comment would be.

Not if you use a nice IDE: https://www.jetbrains.com/help/idea/investigate-changes.html...
Post reply on HN