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

111–120 of 120 posts

Re: Code only says what it does

#111

Post by ChrisMarshallNY »

thdrdt wrote: post #109
ekimekim wrote: post #108

Earlier quoted context omitted.

Or perhaps even better: let iterations = 3 // We need to iterate 3 times for the value to stabilize

Yes, I think your example is better because "// Set the value of b to the number of iterations we'll be making" is almost the same as "/ Set the value of b to 3" when the code explains that `b` is used for the iterations.

I actually take it forward a bit more in that article, to where clear naming eliminates the need for a comment at all:

-

With a good name, we could probably do away with the comment entirely:

let numberOfIterations = 3

-

It’s a fairly exhaustive article (but kind of a long read).

Documentation is an important topic.

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

Re: Code only says what it does

#112

Post by aflag »

kevinschumacher wrote: post #56
aflag wrote: post #52

Earlier quoted context omitted.

Which tool do you use to view commit messages and revisions for each file? I think one of the reasons this is uncommon is due to lack of tooling (or wide-spread knowledge of them). I'd really like to be able to easily see all the previous commits that affected a specific line while I'm editing code. But I usually have to resort to interacting with git, rather than having something popping up on my screen (I use pycha…

Not the person you were replying to, but in PyCharm: - right click on the line number, click Annotate; this gives you the commit date and author in the gutter - hover over the date/author name; this gives you the commit hash and message - click on the hash itself in the popover; this shows the git commit graph on the Version Control tab - right click on the date/author name, click Annotate Revision; this opens up the…

That's nice, and setting the options to detect movements really improves it. It'd be nice to see the commit message, rather than the author, without the need to hovering, though.

Re: Code only says what it does

#113

Post by Kwantuum »

trixie_ wrote: post #13

If I had a nickel for every programmer who thought their code was so good it didn't require comments... or thinks somehow that unit tests make up for comments... only to come back years later and have no idea why the logic is working how it is.

Self-documenting code is not a judgment that you can pass on your own code: that's the role of code review.

95% of the code you write day to day should be clear enough that someone who didn't write it can understand it on first read (the reviewer). If they can't, you probably need to rewrite the code so that it is clearer, not comment it. That's what self-documenting code is.

Instances where the code needs comments to be understandable are rare.

Re: Code only says what it does

#114

Post by dekhn »

hinkley wrote: post #69
dkarl wrote: post #33

This is a major problem with code: You don't know which quirks are load-bearing. You may remember, or be able to guess, or be able to puzzle it out from first principles, or not care, but all of those things are slow and error-prone. This is a problem from both the negative (not breaking things) and positive (knowing how to add things) perspectives. The positive perspective was written about by Peter Naur in one of m…

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 use the scientific process constantly while shipping code (most of my time is spent writing fixes for large production systems that are being actively used, where a regression could cost millions of dollars). In particular, I explicitly state my hypotheses, and use positive and negative control experiments when evaluating my fix.

I often "build one to throw away", but half the time what I build is good enough that it goes into production and lasts for a while.

Re: Code only says what it does

#115

Post by jbay808 »

tigershark wrote: post #105
jbay808 wrote: post #103

Earlier quoted context omitted.

I don't even mind if the comments restate what the code says. The code only says what it does, not what it is intended to do.

The tests say what the code is supposed to do. And, unlike the comments, they cannot be out of sync with the code because they will fail.

Ok, so for example, let's say I have a function npow2(x) that returns the next power of two above x, unless x is a power of 2 already, in which case it returns x. And I want to use this to get the next power of 2 below x.

I can write:

y = npow2(x+1)/2; //get y such that the next power of 2 above y is at least x.

The comment says exactly what the code does, but at least it also says that that's what it's intended to do. This lets a reviewer check correctness, add optimizations, and also understand the intentions at a glance. The why is important too, of course.

Now I could alternatively add unit tests that specify a large number of input cases in which the output happens to be the previous power of 2. But unless I make the test cases exhaustive, I'm only hinting at what this code should do, not defining or explaining it.

I could break this out into a function too, called prevpow2(x), which might or might not be appropriate in this case. But if so, I'd expect that function to have a docstring explaining... exactly the same thing as the above inline comment: what the function supposedly does.

Re: Code only says what it does

#116

Post by jackhiggs »

cloogshicer wrote: post #41

The huge value that I see in a formal specification language like TLA+ is that we could have a precise way of communicating the problem in a way that is agnostic to the implementation language. Imagine something like StackOverflow, but instead of posting a question, you post a formal spec. Thinking even further, you could then find a way to combine/interface these specs and build something like a global database of c…

What you're talking about there is a Model Repository. We're building one at the bank I work at, except because our modelling language (or meta model) is based on OMG's MOF we can generate artifacts (code) from our models. You can't do that with TLA+ as far as I know. It's pretty powerful - you can compose models together very easily, as well as generate loads of useful things for data-in-motion.

Re: Code only says what it does

#117

Post by ellenafam33 »

Hey, I am Ellena Faming I am a tech enthusiast and part time blogger. It would mean the world to me if you visit my website. I live with my brother in London United Kingdom, he is very friendly we both are good writers and gamer. Click the link and visit my website. https://www.eofoodanddrink.com/best-restaurants-paris/

Re: Code only says what it does

#118

Post by tigershark »

jbay808 wrote: post #115
tigershark wrote: post #105

Earlier quoted context omitted.

The tests say what the code is supposed to do. And, unlike the comments, they cannot be out of sync with the code because they will fail.

Ok, so for example, let's say I have a function npow2(x) that returns the next power of two above x, unless x is a power of 2 already, in which case it returns x. And I want to use this to get the next power of 2 below x. I can write: y = npow2(x+1)/2; //get y such that the next power of 2 above y is at least x. The comment says exactly what the code does, but at least it also says that that's what it's intended to d…

Adding a comment there is not useful, it should be added only in the function definition if needed. In this case it’s needed because the function does something unexpected. I would call it nextPower2(n) rather than npow2 and add a comment in the definition saying that the function returns n if n is a power of 2 because it’s unexpected and it can’t be inferred looking at the function name. As I said before, comments for unexpected behaviours are not only perfectly fine but extremely important. Also removing all the useless comments will increase the relative importance of the ones remaining since you will have only comments for really important stuff.

Edit: And anyway in the tests you should have at least these two test cases:

Test nextPower2 returns n if it’s a power of 2

Test nextPower2 returns the next power of 2 if n is not a power of 2

Re: Code only says what it does

#119

Post by cloogshicer »

jackhiggs wrote: post #116
cloogshicer wrote: post #41

The huge value that I see in a formal specification language like TLA+ is that we could have a precise way of communicating the problem in a way that is agnostic to the implementation language. Imagine something like StackOverflow, but instead of posting a question, you post a formal spec. Thinking even further, you could then find a way to combine/interface these specs and build something like a global database of c…

What you're talking about there is a Model Repository. We're building one at the bank I work at, except because our modelling language (or meta model) is based on OMG's MOF we can generate artifacts (code) from our models. You can't do that with TLA+ as far as I know. It's pretty powerful - you can compose models together very easily, as well as generate loads of useful things for data-in-motion.

Hey, thanks a lot for your response! It's really hard to search for abstract ideas like this if you don't know the terminology (like Model Repository), so this is super helpful. This is a very interesting topic for me, may I ask you a few questions? I sent you a request on LinkedIn.

Re: Code only says what it does

#120

Post by jbay808 »

tigershark wrote: post #118
jbay808 wrote: post #115

Earlier quoted context omitted.

Ok, so for example, let's say I have a function npow2(x) that returns the next power of two above x, unless x is a power of 2 already, in which case it returns x. And I want to use this to get the next power of 2 below x. I can write: y = npow2(x+1)/2; //get y such that the next power of 2 above y is at least x. The comment says exactly what the code does, but at least it also says that that's what it's intended to d…

Adding a comment there is not useful, it should be added only in the function definition if needed. In this case it’s needed because the function does something unexpected. I would call it nextPower2(n) rather than npow2 and add a comment in the definition saying that the function returns n if n is a power of 2 because it’s unexpected and it can’t be inferred looking at the function name. As I said before, comments f…

The comments are informing the reader about the trick that turns npow2 into prevpow2. Your reply seems focused on npow2 itself, not the line npow2(x+1)/2 that I said deserves a comment. I agree that npow2 should have the tests and documentation that you say, but in my example I'm taking that function as given, eg. by a library.
Post reply on HN