5 ms·

The first implementation is bad. It’s less stuff to type, but if you’re parsing it, you’re trying to understand it, and the second implementation makes the mean

by pivo 4y ago

The first implementation is bad. It’s less stuff to type, but if you’re parsing it, you’re trying to understand it, and the second implementation makes the meaning clear while the first implementation is mostly meaningless. Code is written once but read many times. Be kind to your readers, which includes yourself in the future.

dusted 4y ago
I strongly disagree. My comment was from my immediate experience parsing what he wrote right there and then. The first one is easy to read and quick to understand, the second on is already like "oh god, now comes a bunch of stuff" and then "okay, he declares that, it's this.. fine" "Okay, he declared this thing and then the other thing is part of that, yeah" and finally "oh, okay he wanted a variable named X with a pair<string, pair<string,string>> geesh fuck just get to the point already!" Like, seriously, it's like the analogy with the little kid explaining every little thing in excruciating detail, actually managing to make it sound like something is happening while nothing's happening.. Don't talk up this giant thing and tell me what you want to tell me.
- phailhaus 4y ago
  > The first one is easy to read and quick to understand No it's not. Let's look at it again: val x: Pair<String, Pair<String, String>> What does x represent? You don't know. Actually, there's no way for you to know what the person writing this code meant when they defined this variable. Sure, you know its structure, but how is it meant to be used in the context of the application? This is one difference between junior and more experienced engineers. Junior engineers know what they meant when they wrote the code, but often forget to consider their teammates or future selves.
  - ethanwillis 4y ago
    The difference is that self-documenting code is bad. Code isn't documentation for humans. Documentation is documentation for humans. One comment right above this that gives a direct example of what x "is", is easier to understand. And then the structure of this line is also easier to understand more quickly than the second example. Is this bad? // A tuple defining an item with a status. (item-name (status-key status-value)) val x: Pair<String, Pair<String, String>> But even knowing what x "is" either with documentation or with verbose "self-documenting code" it still doesn't answer your question of "how this code should be used in the context of the application" Do we save x somewhere? Do we fetch something from somewhere else based on status-key? None of this is known. You get that from description, you get that from surrounding context. Except if we write all of our code like the second example then when we start reading the surrounding context it's going to be more painful. We're hiding the structure with extra verbosity in the pursuit of not having to write documentation or use the best tool we have for communicating with other humans... natural language.
    - stirfish 4y ago
      >The difference is that self-documenting code is bad. Code isn't documentation for humans. Documentation is documentation for humans. Surely you're joking? Code is meant to be read by humans. The comment above your single-letter variable doesn't count - just give it a proper name and use the type system.
      - ethanwillis 4y ago
        The single letter variable is present in the second example for the thread that prompted my response. So the "single letter variable" argument is simply irrelevant. Regardless I wouldn't use a single letter variable name like this, so I do agree. And no code is not meant to be read by humans. The generation of programming languages we have are simply the best we could come up with so far to approximate natural language. They're easier to read than previous languages, but they're not even close in expressive power to natural language. Do we talk in code when discussing what a feature is or should do? Generally no. Do we use code to communicate in standups? Generally no. I don't see how it's joking to make the claim that humans understand natural language descriptions better and more readily than code descriptions. As far as using the type system to document in this case. It just all depends on the context and the actual purpose of this code (which we were not given). My opinion is don't go out of your way to add more layers of abstraction just so you can have types with specific names. It's only warranted in my mind to do this when you need to add complex functionality specific to a type. We very well might not need to do any of that. But unfortunately neither of the examples, even the self-documenting style one, explain the actual purpose of this code to us. Maybe if they had a bit more description for humans we could ponder on it further. Also which would you rather change, a type system, or a comment?
        stirfish 4y ago
        Have you ever seen some sheet music, a schematic, or an equation and thought it would be more clearly expressed as a paragraph of English text? Those are meant to be read by humans too. You don't have to abstract everything, but I like to use a type to add meaning. `String` and `Pair` are especially vague. Was it `UserName` or `UserId`? Was this the status code, or the message we want to display to the user? These are questions that can be answered (and mistakes that can be prevented!) by the type system. You can't get that with just a comment.
  - tjrDL6MjB2Zwwa 4y ago
    both snippets suffer from being stringly typed, that is not what is being discussed. Change the string types to something else mentally if it bothers you that much. It was an example.
tjrDL6MjB2Zwwa 4y ago
No way, the first one I understood the intent with a single pass, the second one had me jumping across all 3 lines to understand. Succinctness is a virtue when used correctly.

by pivo 4y ago

dusted 4y ago

I strongly disagree. My comment was from my immediate experience parsing what he wrote right there and then. The first one is easy to read and quick to understand, the second on is already like "oh god, now comes a bunch of stuff" and then "okay, he declares that, it's this.. fine" "Okay, he declared this thing and then the other thing is part of that, yeah" and finally "oh, okay he wanted a variable named X with a pair<string, pair<string,string>> geesh fuck just get to the point already!" Like, seriously, it's like the analogy with the little kid explaining every little thing in excruciating detail, actually managing to make it sound like something is happening while nothing's happening.. Don't talk up this giant thing and tell me what you want to tell me.

phailhaus 4y ago
> The first one is easy to read and quick to understand No it's not. Let's look at it again: val x: Pair<String, Pair<String, String>> What does x represent? You don't know. Actually, there's no way for you to know what the person writing this code meant when they defined this variable. Sure, you know its structure, but how is it meant to be used in the context of the application? This is one difference between junior and more experienced engineers. Junior engineers know what they meant when they wrote the code, but often forget to consider their teammates or future selves.
- ethanwillis 4y ago
  The difference is that self-documenting code is bad. Code isn't documentation for humans. Documentation is documentation for humans. One comment right above this that gives a direct example of what x "is", is easier to understand. And then the structure of this line is also easier to understand more quickly than the second example. Is this bad? // A tuple defining an item with a status. (item-name (status-key status-value)) val x: Pair<String, Pair<String, String>> But even knowing what x "is" either with documentation or with verbose "self-documenting code" it still doesn't answer your question of "how this code should be used in the context of the application" Do we save x somewhere? Do we fetch something from somewhere else based on status-key? None of this is known. You get that from description, you get that from surrounding context. Except if we write all of our code like the second example then when we start reading the surrounding context it's going to be more painful. We're hiding the structure with extra verbosity in the pursuit of not having to write documentation or use the best tool we have for communicating with other humans... natural language.
  - stirfish 4y ago
    >The difference is that self-documenting code is bad. Code isn't documentation for humans. Documentation is documentation for humans. Surely you're joking? Code is meant to be read by humans. The comment above your single-letter variable doesn't count - just give it a proper name and use the type system.
    - ethanwillis 4y ago
      The single letter variable is present in the second example for the thread that prompted my response. So the "single letter variable" argument is simply irrelevant. Regardless I wouldn't use a single letter variable name like this, so I do agree. And no code is not meant to be read by humans. The generation of programming languages we have are simply the best we could come up with so far to approximate natural language. They're easier to read than previous languages, but they're not even close in expressive power to natural language. Do we talk in code when discussing what a feature is or should do? Generally no. Do we use code to communicate in standups? Generally no. I don't see how it's joking to make the claim that humans understand natural language descriptions better and more readily than code descriptions. As far as using the type system to document in this case. It just all depends on the context and the actual purpose of this code (which we were not given). My opinion is don't go out of your way to add more layers of abstraction just so you can have types with specific names. It's only warranted in my mind to do this when you need to add complex functionality specific to a type. We very well might not need to do any of that. But unfortunately neither of the examples, even the self-documenting style one, explain the actual purpose of this code to us. Maybe if they had a bit more description for humans we could ponder on it further. Also which would you rather change, a type system, or a comment?
      - stirfish 4y ago
        Have you ever seen some sheet music, a schematic, or an equation and thought it would be more clearly expressed as a paragraph of English text? Those are meant to be read by humans too. You don't have to abstract everything, but I like to use a type to add meaning. `String` and `Pair` are especially vague. Was it `UserName` or `UserId`? Was this the status code, or the message we want to display to the user? These are questions that can be answered (and mistakes that can be prevented!) by the type system. You can't get that with just a comment.
- tjrDL6MjB2Zwwa 4y ago
  both snippets suffer from being stringly typed, that is not what is being discussed. Change the string types to something else mentally if it bothers you that much. It was an example.

tjrDL6MjB2Zwwa 4y ago

No way, the first one I understood the intent with a single pass, the second one had me jumping across all 3 lines to understand. Succinctness is a virtue when used correctly.