6 ms·

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 whe

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.com/news/124 https://web.archive.org/web/20210226004600/http://antirez.co... (I still don't understand why he deleted his blog)

cpach 5y ago
Huh? That URL is still alive: http://antirez.com/news/124 http://antirez.com/news/124
- codethief 5y ago
  Huh? I've been getting > Sorry, I can't find that page :-/ for several months
  - ReactiveJelly 5y ago
    Works with pure HTTP. Try it in curl? Also see my sister comment for elaboration
- ReactiveJelly 5y ago
  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.
  - kyleee 5y ago
    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
    - brazzledazzle 5y ago
      A bit snarky but I agree, it doesn’t seem like a huge threat. I’d love to be proven wrong though.
    - Gh0stRAT 5y ago
      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/comcast-using-packet-injection-to-push-its-own-ads-via-wifi-apparently-oblivious-to-security-concerns.shtml https://www.techdirt.com/articles/20140908/07191228453/comca...
    - sinsterizme 5y ago
      How about not opening the gates for third parties to inject ads, trackers and crypto miners
    - cpach 5y ago
      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.
  - codethief 5y ago
    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 5y ago
      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 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 5y ago
        Looks like the cert is for a different domain (redis.io) AND it expired August 7, 2020.
abootstrapper 5y ago
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 5y ago
  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 5y ago
    > 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 5y ago
    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).
PebblesRox 5y ago
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."
audit 5y ago
Thank you for this link. I appreciated antirez's categorization: " During my research I identified nine types of comments: - * Function comments - * Design comments - * Why comments - * Teacher comments - * Checklist comments - * Guide comments - * Trivial comments - * Debt comments - * Backup comments " I tend to write 'debate comments' of the software that I write for my own business (sole proprietor). I think they fit the 'why' category above. I often doubt my own decision making process, so I tend to write it out in comments, so that I can I can see reasoning. My general challenge with comments is of 'maintanence'. The tools to maintain comments, cross link them across diagrams or other hand-written documents -- are hard to find. So am gradually switching to my own directive that 'all documents about implementation, the API and their usage, are to be generated from my comments'. Again, not a lot of tools that I found in this area, but at least it is possible to write my own tools (using IDE APIs) in this area.

cpach 5y ago

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

codethief 5y ago
Huh? I've been getting > Sorry, I can't find that page :-/ for several months
- ReactiveJelly 5y ago
  Works with pure HTTP. Try it in curl? Also see my sister comment for elaboration
ReactiveJelly 5y ago
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.
- kyleee 5y ago
  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
  - brazzledazzle 5y ago
    A bit snarky but I agree, it doesn’t seem like a huge threat. I’d love to be proven wrong though.
  - Gh0stRAT 5y ago
    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/comcast-using-packet-injection-to-push-its-own-ads-via-wifi-apparently-oblivious-to-security-concerns.shtml https://www.techdirt.com/articles/20140908/07191228453/comca...
  - sinsterizme 5y ago
    How about not opening the gates for third parties to inject ads, trackers and crypto miners
  - cpach 5y ago
    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.
- codethief 5y ago
  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 5y ago
    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 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 5y ago
      Looks like the cert is for a different domain (redis.io) AND it expired August 7, 2020.

abootstrapper 5y ago

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 5y ago
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 5y ago
  > 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 5y ago
  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).

PebblesRox 5y ago

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

audit 5y ago

Thank you for this link. I appreciated antirez's categorization: " During my research I identified nine types of comments: - * Function comments - * Design comments - * Why comments - * Teacher comments - * Checklist comments - * Guide comments - * Trivial comments - * Debt comments - * Backup comments " I tend to write 'debate comments' of the software that I write for my own business (sole proprietor). I think they fit the 'why' category above. I often doubt my own decision making process, so I tend to write it out in comments, so that I can I can see reasoning. My general challenge with comments is of 'maintanence'. The tools to maintain comments, cross link them across diagrams or other hand-written documents -- are hard to find. So am gradually switching to my own directive that 'all documents about implementation, the API and their usage, are to be generated from my comments'. Again, not a lot of tools that I found in this area, but at least it is possible to write my own tools (using IDE APIs) in this area.