[codethief]

Speaking of source code comments, antirez (of Redis fame) wrote a fantastic article[0] about that topic some time ago and I still recommend it to colleagues whenever they make the hollow statement that "code should and can be intelligible on its own, without any comments".

[0]: https://web.archive.org/web/20210226004600/http://antirez.co... (I still don't understand why he deleted his blog)

[PebblesRox]

I love this line: "Comments are rubber duck debugging on steroids, except you are not talking with a rubber duck, but with the future reader of the code, which is more intimidating than a rubber duck, and can use Twitter."

[abootstrapper]

I agree with you. Code should be intelligible on its own without comments. It should also be well documented. One does not preclude the other.

[cratermoon]

I've forgotten who first wrote this, so I can't credit them, but there's a saying that if someone can't write clear, clean, and understandable code, why does anyone expect them to be able to write clear, clean, and understandable English (or whatever language)?

It's quite a bit easier to write something the compiler or runtime can understand, there's no need for meaningful names, consistent structure, or conceptual coherence. As long as it builds and passes whatever tests, the computer will accept it.

[nicoburns]

> if someone can't write clear, clean, and understandable code, why does anyone expect them to be able to write clear, clean, and understandable English

Isn't the answer to that obvious? The code is significantly constrained in form by having to be executable. The comments have no such restriction.

[codethief]

While surely not the source of the saying, antirez argues in a similar direction:

> You may think that writing comments is a lesser noble form of work. After all you can code! However consider this: code is a set of statement and function calls, or whatever your programming paradigm is. Sometimes such statements do not make much sense, honestly, if the code is not good. Comments require always to have some design process ongoing, and to understand the code you are writing in a deeper sense. On top of that, in order to write good comments, you have to develop your writing skills. The same writing skills will assist you writing emails, documentation, design documents, blog posts, and commit messages.

In any case, you're making a good point, though I would argue that the reverse of the saying (with the modification that "expectations" get replaced with "trust") also holds:

If someone is not able to write intelligible, stringent English, I wouldn't trust them to write good code, either, because writing good code requires similar qualities (good stringent structure, empathizing with the future reader of your code etc.) and, as antirez argues convincingly, it also requires writing comments (which are in plain English).

[einpoklum]

> if someone can't write clear, clean, and understandable code, why does anyone expect them to be able to write clear, clean, and understandable English (or whatever language)?

The comments don't say the same thing as the code. In the comments, the author might tell us - albeit not clearly or in proper English, what they want to achieve, or why they're doing it this way.

[cratermoon]

If someone takes a dozen lines of convoluted code to express what can be done in 2-3 lines concisely, the explanation isn't going to help. Think of the worst mess of if/then/else clauses you've seen, or someone who switches on a type instead of using polymorphism. Even if they can explain it well enough that you can follow it, the comments aren't going to improve the understanding much. They are more likely to add cognitive load and make it harder to grasp the intent.

[philosopher1234]

Comments are not for fixing bad code, comments are for explaining complex (and good) systems.

[unchar1]

I first heard that in a talk by Kevlin Henney [1]. I'm not sure if he's the one who came up with it though.

[1]: https://twitter.com/KevlinHenney/status/381021802941906944

[cratermoon]

I'm a big fan of Henney and have watched a lot of videos of his talks, so that's probably it.

[codethief]

I'm not sure we agree. But I guess the question comes down to what you and I mean by "intelligible".

antirez provides several examples where the code without the comments would be much harder to understand and/or maintain. Whenever this is the case, I would argue that comments are a must and without them the code is at least barely intelligible.

[Koshkin]

Very often it is just not possible to truly understand code without comments (or other form of documentation). This becomes obvious if you realize that code by itself can only tell you what is being done, but not why.

[cpach]

Huh? That URL is still alive: http://antirez.com/news/124

[ReactiveJelly]

Maybe it's a buggy HTTPS redirect in GP's browser? Due to HSTS or something?

The HTTP version of your URL works fine. The HTTPS version has an expired cert. If I click past that, it redirects to redis.io, then gives a 404.

I know antirez is a smart guy, but if this is some kind of "I'm taking a bold stance against HTTPS" then I'd rather read the archive.org link with functioning HTTPS. My threat model prefers trusting archive.org to correctly reproduce the blog, over trusting everyone between me and antirez.com.

[codethief]

Wow, you just opened my eyes – I really thought he had deleted his blog! Must be the HTTPS Everywhere extension I'm using – though I really don't understand why it redirects me to redis.io just because antirez's TLS certificate is for redis.io, not antirez.com. I would really prefer a clear error message here.

[cpach]

The web server(s) at antirez.com are weirdly configured. So it’s not so easy for the web browser to display a very clear error message in this case.

If you run this command you can see a little more clearly what’s going on:

  wget --no-check-certificate -S -O - https://antirez.com/news/124

If you use the plain HTTP URL, everything works fine.

If you try https://antirez.com/news/124 the web server at antirez.com:443 will answer this:

  HTTP/1.1 301 Moved Permanently
  Server: nginx/1.10.2
  Date: Sat, 04 Sep 2021 18:15:46 GMT
  Content-Type: text/html
  Content-Length: 185
  Connection: keep-alive
  Location: https://redis.io/news/124

So it’s not HTTPS Everywhere that redirects, it’s the web server itself.

However, many clients won’t heed this response, since antirez.com:443 serves a certificate that’s not valid for that hostname.

[cratermoon]

Looks like the cert is for a different domain (redis.io) AND it expired August 7, 2020.

[kyleee]

Let's hear more about your threat model that causes you to wory about nefarious content being injected into a blog post about comments in code

[Gh0stRAT]

Not OP, but residential ISPs were caught injecting ads into HTTP sites at least as early as 2014. [0]

I certainly wouldn't trust Comcast to keep malicious ads out of their ad network, either.

[0] https://www.techdirt.com/articles/20140908/07191228453/comca...

[sinsterizme]

How about not opening the gates for third parties to inject ads, trackers and crypto miners

[cpach]

I agree that in this case (reading an article) HTTP is not a huge threat. But in 2021 I consider HTTPS + HSTS to be a basic hygiene factor.

[brazzledazzle]

A bit snarky but I agree, it doesn’t seem like a huge threat. I’d love to be proven wrong though.

[codethief]

Huh? I've been getting

> Sorry, I can't find that page :-/

for several months

[ReactiveJelly]

Works with pure HTTP. Try it in curl? Also see my sister comment for elaboration