6 ms·

The author seems to like the minimalistic comments. I wonder if the team looked back what their thoughts would be. I can barely look at code I wrote a year ag

The author seems to like the minimalistic comments. I wonder if the team looked back what their thoughts would be. I can barely look at code I wrote a year ago and not ask what the hell I was thinking, but in my mind it was absolutely clear at the time. I guess an impartial third party reading it and understanding it is a strong testimonial.

RyanZAG 14y ago
The key is to have self documenting code, not undocumented code. If you create functions that do only a single thing, with their purpose fully described by their method signature then you don't need comments - the method itself explains exactly what it does. The author makes a good point that comments are just more text that you need to maintain, and whenever you make changes you now have to make changes in two places: in the code, and in the comment - (and I guess in the unit tests as well, depending on the change...) The best code I've personally seen has been code with no comments and an attached document explaining how the system works and how modules tie together.
- nirvdrum 14y ago
  Oh, I get the concept. I've just been doing this for a while and see it fall part constantly. The problem is always that what is clear to you isn't clear to everyone else, including yourself somewhere down the road. And decomposing everything to atoms tends to lead to a mess of indirection. Clarity can usually be addressed with longer variable or method names, but there's a strong culture against that in nearly ever programming community.
  - scanr 14y ago
    > Clarity can usually be addressed with longer variable or method names, but there's a strong culture against that in nearly ever programming community. It would be interesting to see a list of those that discourage long method and variable names. I haven't seen anything that suggests that Java, Ruby, Python, Haskell, Kotlin, Scala, PHP, Groovy etc. discourage long variable and method names.
    - nirvdrum 14y ago
      IntelliJ has inspections for long class and method names. A lot of Java devs run that. Long names are frequently derided in the Ruby community as being Java-like. I can't speak to Haskell at all. But generally whenever something needs to be typed frequently, it tends to be shortened. My favorite is when vowels are deemed too onerous.
      - mercurial 14y ago
        Haskell is a special beast, in the sense that it uses single letters a lot for generic types in signatures. Eg: doFoo :: a -> a where doFoo will take any type a and return something of the same type. Due to the density of the language, you'll often find plenty of small, commented functions.
        Tyr42 14y ago
        Compare doubleCompose binary_func transformation first_arg second_arg = binary_func (transformation first_arg) (transformation second_arg) vs doubleCompose (b -> b -> c) -> (a -> b) -> a -> a -> c doubleCompose (+) f x y = (f x) + (f y) (also known as the `on` function). There's hardly any good names for x and y, since they can be anything at all.
        mercurial 14y ago
        Your verbose version is just the core of the function, not the type signature. I'm not really sure of what you want to demonstrate here. That short names are good ?
        eru 14y ago
        Our guidelines at work are: The more polymorphic a variables type, the shorter its name can be.
      - scanr 14y ago
        While I was writing that, I realised that it may come down to the definition of what constitutes a long method / variable / class name. I have usually found that the IntelliJ defaults are enough to make the names meaningful. For Ruby, the inspection kicks in at 30 characters. Interestingly, it's referenced from the ruby style guide here: https://github.com/bbatsov/ruby-style-guide https://github.com/bbatsov/ruby-style-guide where I can't find a recommended maximum length. We're somewhat sidetracked from the main discussion. I'm generally in favour of trying to write code that is as readable as possible. Ideally in such a way that it is understandable even without the comments. That said, I do think that good comments are helpful and essential if you're building a library. The Spring Framework comes to mind as a project that has a great set of documentation built from the comments (but also has very readable code, along with long method, variable and class names).
- lordlicorice 14y ago
  For me, external documentation is the absolute worst scenario. It takes me at least 4 times longer to read through and understand code without comments explaining in English what's going on. Here's a real-life example: // Toggle between Dropdown and Text if(_protected.fields[field].fieldType() === "Dropdown") { _protected.fields[field].set("fieldType", "Text"); } else { _protected.fields[field].set("fieldType", "Dropdown"); } I think it would take me about 4 seconds to figure out that this code "toggles between Dropdown and Text" if the comment weren't there. Since the comment is there, I can just glance at the code and understand immediately what it does.
  - RyanZAG 14y ago
    Rather have code that looks like this: toggleDropdown(field) { if ... } toggleDropdown(_protected.fields[field]); Also the external documentation wouldn't have anything like this in it. It would be pretty much: UI Code is in XXX. It communicates with ZZZ using YYY. Fields in the UI are changed between text and dropdowns depending on the value in the database that comes from ZZZ. etc.

RyanZAG 14y ago

The key is to have self documenting code, not undocumented code. If you create functions that do only a single thing, with their purpose fully described by their method signature then you don't need comments - the method itself explains exactly what it does. The author makes a good point that comments are just more text that you need to maintain, and whenever you make changes you now have to make changes in two places: in the code, and in the comment - (and I guess in the unit tests as well, depending on the change...) The best code I've personally seen has been code with no comments and an attached document explaining how the system works and how modules tie together.

nirvdrum 14y ago
Oh, I get the concept. I've just been doing this for a while and see it fall part constantly. The problem is always that what is clear to you isn't clear to everyone else, including yourself somewhere down the road. And decomposing everything to atoms tends to lead to a mess of indirection. Clarity can usually be addressed with longer variable or method names, but there's a strong culture against that in nearly ever programming community.
- scanr 14y ago
  > Clarity can usually be addressed with longer variable or method names, but there's a strong culture against that in nearly ever programming community. It would be interesting to see a list of those that discourage long method and variable names. I haven't seen anything that suggests that Java, Ruby, Python, Haskell, Kotlin, Scala, PHP, Groovy etc. discourage long variable and method names.
  - nirvdrum 14y ago
    IntelliJ has inspections for long class and method names. A lot of Java devs run that. Long names are frequently derided in the Ruby community as being Java-like. I can't speak to Haskell at all. But generally whenever something needs to be typed frequently, it tends to be shortened. My favorite is when vowels are deemed too onerous.
    - mercurial 14y ago
      Haskell is a special beast, in the sense that it uses single letters a lot for generic types in signatures. Eg: doFoo :: a -> a where doFoo will take any type a and return something of the same type. Due to the density of the language, you'll often find plenty of small, commented functions.
      - Tyr42 14y ago
        Compare doubleCompose binary_func transformation first_arg second_arg = binary_func (transformation first_arg) (transformation second_arg) vs doubleCompose (b -> b -> c) -> (a -> b) -> a -> a -> c doubleCompose (+) f x y = (f x) + (f y) (also known as the `on` function). There's hardly any good names for x and y, since they can be anything at all.
        mercurial 14y ago
        Your verbose version is just the core of the function, not the type signature. I'm not really sure of what you want to demonstrate here. That short names are good ?
        eru 14y ago
        Our guidelines at work are: The more polymorphic a variables type, the shorter its name can be.
    - scanr 14y ago
      While I was writing that, I realised that it may come down to the definition of what constitutes a long method / variable / class name. I have usually found that the IntelliJ defaults are enough to make the names meaningful. For Ruby, the inspection kicks in at 30 characters. Interestingly, it's referenced from the ruby style guide here: https://github.com/bbatsov/ruby-style-guide https://github.com/bbatsov/ruby-style-guide where I can't find a recommended maximum length. We're somewhat sidetracked from the main discussion. I'm generally in favour of trying to write code that is as readable as possible. Ideally in such a way that it is understandable even without the comments. That said, I do think that good comments are helpful and essential if you're building a library. The Spring Framework comes to mind as a project that has a great set of documentation built from the comments (but also has very readable code, along with long method, variable and class names).
lordlicorice 14y ago
For me, external documentation is the absolute worst scenario. It takes me at least 4 times longer to read through and understand code without comments explaining in English what's going on. Here's a real-life example: // Toggle between Dropdown and Text if(_protected.fields[field].fieldType() === "Dropdown") { _protected.fields[field].set("fieldType", "Text"); } else { _protected.fields[field].set("fieldType", "Dropdown"); } I think it would take me about 4 seconds to figure out that this code "toggles between Dropdown and Text" if the comment weren't there. Since the comment is there, I can just glance at the code and understand immediately what it does.
- RyanZAG 14y ago
  Rather have code that looks like this: toggleDropdown(field) { if ... } toggleDropdown(_protected.fields[field]); Also the external documentation wouldn't have anything like this in it. It would be pretty much: UI Code is in XXX. It communicates with ZZZ using YYY. Fields in the UI are changed between text and dropdowns depending on the value in the database that comes from ZZZ. etc.