Hacker News Reader

Comment by nirvdrum | Hacker News Reader

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.

View on HN

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.

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.

> 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.

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.

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 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).

I can get on board with common sense decision making :-)

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.

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.

Our guidelines at work are: The more polymorphic a variables type, the shorter its name can be.

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 ?

The Haskell community certainly love their infix non-alphanumeric functions.

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.

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.

Reply on news.ycombinator.com