Code only says what it does • Hacker News Board

Re: Code only says what it does

#61

Post by dllthomas » Mon, Jul 06, 2020, 9:12 PM UTC

baddox wrote: post #23

henryfjordan wrote: post #17

Earlier quoted context omitted.

Tests that target the surfaces of the project (public APIs, endpoints, etc) and code examples start to blend together at some point. "Here's a basic example that should do X" sounds a lot like "Do something basic and assert it does X".

I think the biggest problem with using unit tests for this purpose is that unit tests tend to (rightfully) spend a disproportionate amount of lines of code on edge cases.

Where applicable, this is what doctests are for, and they're magical. ... where applicable.

Re: Code only says what it does

#62

Post by phendrenad2 » Mon, Jul 06, 2020, 9:21 PM UTC

wanderr wrote: post #60

phendrenad2 wrote: post #45

It gives me no end to pain that "Comments are lies because they aren't code" is a fad that we're currently suffering through as an industry. For decades prevailing wisdom was that comments were a net benefit, and now in the last few years this trend has become prevalent. How much perfectly-good code is going to have to be rewritten from scratch in 10 years because no one remembers what it does?

If no one understands what it does, it's not perfectly good code is it? Of course there are rare cases where code cannot be simplified, made more readable or self explanatory and in those cases comments are vital. But the aim should be for the vast majority of code to be easily readable by humans.

I mean it's "perfectly fine" because the people building it know how it works (because they were there when it was built), and think they don't need comments to help out future maintainers.

Re: Code only says what it does

#63

Post by thdrdt » Mon, Jul 06, 2020, 9:38 PM UTC

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 to lose track on why you did things the way you did.

Comments on why are very helpful.

Re: Code only says what it does

#64

Post by clairity » Mon, Jul 06, 2020, 9:43 PM UTC

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…

yes, comments should be considered code too, but for humans, so later coders (including your later self) can effectively simulate (not but necessarily replicate) the prior code-writing process(es). it's as critical as the code for machines.

which is to say, the comments should be kept concise and current too.

Re: Code only says what it does

#65

Post by nemetroid » Mon, Jul 06, 2020, 9:46 PM UTC

aflag wrote: post #52

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…

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…

I use tig, which is a terminal UI. The "blame" view has a shortcut to jump to the commit before the one that changed a given line. This makes it easy to quickly dig backwards through the history of a file.

Re: Code only says what it does

#66

Post by Jtsummers » Mon, Jul 06, 2020, 9:59 PM UTC

wanderr wrote: post #60

phendrenad2 wrote: post #45

It gives me no end to pain that "Comments are lies because they aren't code" is a fad that we're currently suffering through as an industry. For decades prevailing wisdom was that comments were a net benefit, and now in the last few years this trend has become prevalent. How much perfectly-good code is going to have to be rewritten from scratch in 10 years because no one remembers what it does?

If no one understands what it does, it's not perfectly good code is it? Of course there are rare cases where code cannot be simplified, made more readable or self explanatory and in those cases comments are vital. But the aim should be for the vast majority of code to be easily readable by humans.

Essential versus accidental complexity.

Perfectly good code can be unclear because of the accidental complexity included within it. Memory management, error handling (especially in languages with less expressive type systems), configuring hardware/database/network connections, etc. Those things are important, but they prevent the essential portion of the program from being expressed on its own.

Type systems, a brief example: C versus Ada. Implement a network protocol where the data packet has specific n-bit sized fields with ranges less than the maximum for that size. You can easily do this in both languages. But in C, you'd either need to add bounds checking to all of those fields or risk letting errors propagate. That error handling obscures the essential portion of the program. In Ada, you make a type that is n-bits and only accepts values of the correct range. The errors can still exist in received packets, but the error checking is partially elided from the code because the type system itself can catch it.

There's nothing wrong with the C code, and there's nothing wrong (many will disagree with that) with choosing C to implement the protocol. But it will increase the complexity due to factors beyond the inherent, essential complexity of the network protocol itself.

Re: Code only says what it does

#67

Post by Ma8ee » Mon, Jul 06, 2020, 10:00 PM UTC

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…

A lot of comments can (and should) be replaced with good naming. Sometimes the only reason to introduce a variable or function is to name something. The advantage is that it is harder to not read a name than it is to not read a comment, and it is more obviously a bug when we try to set a variable, or make a function calculate, something not agreeing with its name.

Re: Code only says what it does

#68

Post by recursive » Mon, Jul 06, 2020, 10:04 PM UTC

aflag wrote: post #52

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…

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…

Visual Studio has this. It's called "Annotate".

Re: Code only says what it does

#69

Post by hinkley » Mon, Jul 06, 2020, 10:07 PM UTC

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 the problem space.

During that process I may discover that I based half of my experiment on another hypothesis that I never tested, or was plain wrong. Now I've discovered my 'load bearing' assumptions. I may discover something even more interesting there, or I may slink away having never told anybody about my mistake.

Essentially, scientists still 'build one to throw away'. We haven't in ages. And my read on Brook's insistence that we build one to throw away is that it was aspirational and not descriptive. And notably, he apparently recants in the 20th anniversary edition (which is itself 25 years old now):

> "This I now perceived to be wrong, not because it is too radical, but because it is too simplistic. The biggest mistake in the 'Build one to throw away' concept is that it implicitly assumes the classical sequential or waterfall model of software construction."

So we are very much at odds with the scientific method. And we have the benefit of hindsight. We have seen the horrors that can occur when you take the word Theory out of context and try to apply it to non-scientific theories. We should learn from the mistakes of others and summarily reject any plan where we do it too.

In other words: next metaphor, please, and with all due haste.

Re: Code only says what it does

#70

Post by trixie_ » Mon, Jul 06, 2020, 10:24 PM UTC

tigershark wrote: post #54

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.

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, write comments for yourself first. You will not remember years from now the reasoning that went into the code your wrote.