Hacker News Reader

Comment by tines | Hacker News Reader

I know it's not the point of the article, but, as a code reviewer, this:

> Well written ruby code can often read like natural language. Features like predicate methods even give up punctuation. [...] This is often why ruby programmers don’t like comments. In most cases, the language makes comments unnecessary.

churns my stomach. Good comments are rarely about saying what the code does, they're about explaining _why_ the code does what it does. Regardless of how comprehensible ruby code is, it doesn't change the need for comments. If I had a nickel for every time I gave a commit a -1 review because it had too few comments or the wrong kind of comments or lacked a "why" commit message, I'd be a rich man.

View on HN

Some code needs "why" comments, and other code just needs "what" comments (unless it's written in a clear, high level language; then not).

"Why" comments need to go onto code that make some kind of arbitrary decision. Or code which is integrated with processes that are happening elsewhere and has to behave in a way that complements those behaviors. Otherwise the reader would have to read that code together with all those other pieces (or specifications) in order to understand it. Code that is written in a certain way (particularly, an unusual way) for some reason that is not obvious deserves a "why" comment. E.g. "due to a compiler/library bug [give specific version info], we cannot just do this: ...".

Code that doesn't make arbitrary decisions or integrate with things elsewhere, or make unusual coding decision for reasons, often doesn't require "why" comments.

The author of the article hastened to add:

> And when you do need [comments], it’s often when you’re doing a very specific or obscure thing that requires context to understand. It’s clear from the code why you need a comment in that case.

It's clear from the code why you need a comment, because it's a "why" comment.

One of the features I hope we’ll see in the next generation of source control is having better support for annotating lines of source code with commit message information. We have good old “blame” right now but it’s very easy to lose that information across refactors or reformatting (for example if someone introduces an auto formatter to the codebase, or if you move some code but also edit it such that your tool doesn’t understand the old code and the new code were related.)

Commit messages are such a good place to explain code and I rarely need the same explanation in a comment. I worry though about the fragility of the connection between (a) the source code and (b) the important commits that explain why the code is there.

Perhaps there are some very good UIs out there already that show something a little more intelligent than than the most recent commit from blame?

Another idea might be to attach blame-like functionality to the syntax tree so that the explanatory messaging can be tracked at the function level, rather than as lines of source code. Can others here can point me in the right direction for either a more tangible description of this feature, or an existing research?

There is a git-blame-ignore-revs that you can configure to keep your git blames more useful.

Yes! Well-written code can be a joy to read, but it represents a subset of the total amount of useful information about what's going on in a program or system. Obviously code can be overly and unhelpfully commented, but poorly commented code is usually a very strong indicator of a mediocre programmer.

Why does this function exist? Why was it implemented this way and not that way? Sometimes these are really important bits of info. Here's where this approach breaks down. Here's a sharp edge that we hope to remove someday. This part here incurs some technical debt but this is why we did it.

In order to really maintain a codebase (meaning: safely fix bugs and add new features), you need to have an understanding that at least approaches that of the person who wrote the code originally, and good comments (e.g. level of intent comments) can help you do that. This is true even for your own code that you're returning to after some amount of time.

Occasionally it's necessary to write code that would make people ask, "why?!?" and comments definitely help there, but I feel like that's generally rare, especially when you use good variable/function names, keep functions small, keep nesting to a minimum, and follow all the other good programming practices. If you are writing/reading code and thinking it needs comments, maybe think a little harder about how the code itself could be made more clear.

Comments are not checked by compilers, linters, code formatters, unit tests, integration tests, or any other automated tools for correctness, consistency, and good formatting. They rot quickly.

It's not about the clarity of the code though. It's about things that are uncheckable by compilers, linters, etc. That is to say, when I'm reading code I may perfectly comprehend what the code does. But knowing what it does doesn't help me understand why it does that thing, how it fits into the overall design, and things of that nature.

For example, if code is operating on a list, and then it sorts that list and passes it along to some other code, I can see perfectly that the list will be sorted. But that doesn't tell me _why_ it needed to be sorted in the first place. Often that is not knowable except by reviewing things outside the scope of the code in question, or outside any code at all. A comment is essential in that context.

The example was: ‘if @subscription.supports_feature?(:feature_a)’.

In a different language you might deal with more boilerplate (getting some data access object for feature status, passing the db connection, extracting the subscription id, etc), or less clear naming schemes (importing namespaces, aliasing them for convenience, your subscription might come from some one letter temp variable), or something else. At this point the “why” comment might be not that different from the actual ruby code.

Note that we only see one line of ruby code; the parent method name, or the if body would have more context.

I honestly found that particular example puzzling. I've written code in at least three other languages that would look nearly identical to it. Unless they were referring to the `?`, or perhaps the lack of a trailing `:` / `{` which seems very superficial to me. Maybe the `@` instead of a `self`? Genuinely unsure.

In general yes, there are other languages where this is easy too.

Then again, ruby and rails make it especially easy; perhaps the amount of conventions helps. Other things, like the ‘?’, clean syntax and focus on structure (OO), help too.

Yes, this part of the article seems like nonsense to me. If it didn't have a question mark, we would need a comment? But because the predicate name contains a question mark, that's the only reason why we don't need a comment? That's nonsense.

This only makes sense if we're in the school of thought that writes

i = i + 1 // increment i by one

This is an uncharitable reading; I don't think the author is literally saying that predicate-style methods are a perfect replacement for comments.

The more charitable interpretation is that they're pointing out the developer ergonomics of things like predicate methods remove the need for comments that might otherwise be reasonable to insert. Whether or not that is true is subject to reasonable debate, but it's definitely a more nuanced opinion than "Ruby's predicate idiom means I don't have to document my obvious code."

out of curiosity how many ruby codebases have you worked on?

Why do you ask that? I worked in Ruby at Pivotal, with lots of people who espouse the "comments are just lies waiting to happen" philosophy. I agree with the parent, it's wholly misguided. Good comments save many, many hours of rediscovery by people who are new to the code - which includes the original author after walking away for a few years.

If I had to guess, the anti-comment attitude comes from consultants who re-implement the same CRUD webapp on Rails over and over. Sure - no surprises, no comments, fine.

'cause i have no trouble reading ruby code without comments and neither do most rubyists in my experience

Reading code is easy. What's hard is to read the mind of the programmer who wrote it. The reason we argue about Chesterton's Fence is that Chesterton was too damn lazy to leave a comment.

I love Ruby and this is spot-on. Comments in any language should explain why and not what.

Sure, not justifying code without comments. But keep in mind Ruby is a bit like Lisp, where there is a strong tradition of building DSLs.

Hence, lots of Ruby code is a sequence of trivial declarative blocks that look like natural language.

In these parts of the code, comments are redundant. I think that is the OP's point. Other parts definitely need them.

https://steve-yegge.blogspot.com/2008/02/portrait-of-n00b.ht...

Also, literate programming is a feature of any language. Sure Ruby has punctuation, but is there enough of a difference between `Array#empty?` vs `Array#isEmpty` to break a absolutely not.

I say this as someone who wrote Ruby for 6 years and loves the language for its other features (e.g. everything is an object, functional programming, DSL-capabilities)

I can probably count on one hand the number of comments I've written a comment in over a decode of coding ruby. I've never encountered code I couldn't understand just from reading the code. It really just isn't done in the ruby world. And good - comments are just noise in any language. You need to read the code because comments are wrong often enough (and 1% of the time is more than often enough) you can never trust them.

Consider the overhead of a comment - first you need to read the comment because they are always above the code so that's what your brain will do. This will prejudice your reading of the code.

Then you need to read the code while trying to block the comment prejudice out of your mind.

Then you need to sort of mentally diff the comment and the code, and if the comment is wrong (spoiler...) decide if you are going to delete the comment (the best choice, unless you get a code reviewer who likes comments) or fix the comment (the worst choice, a waste of time, but maybe the only way to get it through code review).

Now consider code without a comment: you just read the code.

Sometimes you just need comments. I’ve written graphing algorithms that traverse databases in Ruby. I named functions well, too; but the actions I was doing were so weird without sufficient context that when someone might need to change it, 6 months or a year from now, they would have absolutely no idea why I was doing. And no amount of clean code patterns, nor code as documentation patterns would have clarified what was being done as much as the multi-paragraph with ascii art comment I wrote above the function.

Sometimes you just need comments.

You're still stuck in the mindset that the comment is about what the code is doing. Good comments are orthogonal to the code they're attached to.

The most challenging part of reading code is the WHY. But is easier said then done when it comes to documenting code with this in mind. Happy medium is to make sure the author peppers in enough context of why something is like this.

Maybe it's a hot take but I even disagree that code that reads like natural language is good.

Is mathematic better when it reads like English? I personally don't think so. Yeah it's a bunch of symbols and conventions to learn but it ends up being more precise.

I dont have anything to back it up :) I just think that natural language is almost by design messy and imprecise so I'm not really looking for that in my code.

My latest comment I wrote was for Ruby legacy code. It was "This method's documentation says it returns a string. That is a lie, it can return an object of any type."

What's even better than comments, is a compiler that actually guarantees you're gonna be given something of the type you expect.

To be fair in a weakly/duck typed languages a string can be an object of any type. The fair question to ask would : do those type quack and walk like a string.

They don't, it was returning settings from a json file and so was returning booleans, ints and floats.

I would even go a step further : I prefer a cryptic code with good comment explaining what the code does and why it does what it's trying to do vs a very clear code with comment on How the code works.

Reply on news.ycombinator.com