Writing Well-Documented Code – Learn from Examples • Hacker News Board

Re: Writing Well-Documented Code – Learn from Examples

#41

Post by rightbyte » Sat, Sep 04, 2021, 6:13 PM UTC

SavantIdiot wrote: post #20

MattGaiser wrote: post #18

I just prefer nice, long, descriptive function names. I was working on an unfamiliar codebase yesterday and had to work with the postMessage function. It was React, so one might assume that it sends the message to the backend, which was my initial assumption. Nope. It posted it to the page. Didn't help that another utility had another postMessage that was about what to do after the message was sent.

I worked with a guy who wrote a CPU simulator and exceeded the MSVC 256-char function name limit. It's hard when you like 80/100 col code and a function name is longer than that.

Does escape new line work in function names in C? Brb.

Edit: Hah. It does.

Re: Writing Well-Documented Code – Learn from Examples

#42

Post by Gh0stRAT » Sat, Sep 04, 2021, 6:15 PM UTC

kyleee wrote: post #22

ReactiveJelly wrote: post #15

Earlier quoted context omitted.

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 trustin…

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

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

Re: Writing Well-Documented Code – Learn from Examples

#43

Post by ainzzorl » Sat, Sep 04, 2021, 6:17 PM UTC

didip wrote: post #11

I have a simple rule to go by. Comments should describe “why” and the code should describe “what”.

While I agree with the general sentiment, the first example in the article IMO demonstrates how "what" comments make understanding code easier. When I first read that code, I was pleasantly surprised how easy it was to understand everything going on there, even though I had no familiarity with the code base. This is rare for non-trivial projects. I'm not sure if it could be made as clear without those comments.

Re: Writing Well-Documented Code – Learn from Examples

#44

Post by sinsterizme » Sat, Sep 04, 2021, 6:17 PM UTC

kyleee wrote: post #22

ReactiveJelly wrote: post #15

Earlier quoted context omitted.

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 trustin…

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

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

Re: Writing Well-Documented Code – Learn from Examples

#45

Post by ahallock » Sat, Sep 04, 2021, 6:17 PM UTC

I like meta comments about the business or technical decisions behind the code. You can come up with clever method and variable names to help enlighten the reader, but nothing beats an intimate, first-hand account explaining the why.

Re: Writing Well-Documented Code – Learn from Examples

#46

Post by cpach » Sat, Sep 04, 2021, 6:20 PM UTC

codethief wrote: post #26

ReactiveJelly wrote: post #15

Earlier quoted context omitted.

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 trustin…

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.

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.

Re: Writing Well-Documented Code – Learn from Examples

#47

Post by tartoran » Sat, Sep 04, 2021, 6:24 PM UTC

MattGaiser wrote: post #18

I just prefer nice, long, descriptive function names. I was working on an unfamiliar codebase yesterday and had to work with the postMessage function. It was React, so one might assume that it sends the message to the backend, which was my initial assumption. Nope. It posted it to the page. Didn't help that another utility had another postMessage that was about what to do after the message was sent.

Better than writing really long descriptive function names is to not get carried away but write well described function names that show some intent or description and are chosen carefully. I worked on some code bases using long descriptive function names (inherited from another dev) and it wasn’t always useful. It was overkill. The descriptions were either too generic, too descriptive (redundant in half the cases) or handling such long saussage names was simply tiring. When you have to scroll right to read a name it becomes a problem..

The takeway is that merely writing very long descriptive names isn’t a silver bullet and could cause harm despite good intentions.

I suggest going back a after a few days for a refactoring (renaming functions or variables) and see how it reads to you. Then repeat the process a few days later when you’re even more detached from that code.

In many cases self documenting code is going to help you remember the model you had in your head when building it. And if done well it will help others as well, your code will end up not giving headaches to future maintainers.

Re: Writing Well-Documented Code – Learn from Examples

#48

Post by tempest_ » Sat, Sep 04, 2021, 6:24 PM UTC

pcmoney wrote: post #36

Personally I found most of those examples to be not great. I think they would be improved better names overall, more well named private methods and most importantly well structured companion test classes proving the behavior. I really dont want to read another developers comments on their mental state while I am feverishly debugging their code during a 3am page. The number of times I have been misled by an outdated c…

That is how I feel about these comments.

In a vacuum I like them and when I bump into a piece of 10 year old code commented like this it is great.

There is one caveat however, they have to be meticulously maintained and always updated to reflect every change made to the code. It is a huge caveat because more often than not the comments are out dated and no longer reflect the actual code and at that point they are detrimental.

Re: Writing Well-Documented Code – Learn from Examples

#49

Post by cpach » Sat, Sep 04, 2021, 6:24 PM UTC

kyleee wrote: post #22

ReactiveJelly wrote: post #15

Earlier quoted context omitted.

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 trustin…

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

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.

Re: Writing Well-Documented Code – Learn from Examples

#50

Post by cratermoon » Sat, Sep 04, 2021, 6:25 PM UTC

abootstrapper wrote: post #35

codethief wrote: post #6

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)

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.

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.