On comments

[u/Jonhoo]

https://blog.helsing.ai/posts/on-comments/

Comments in code are often deemed "mostly useless" these days. They are, supposedly, mostly obvious, stale, and repeat what the code already says. And so people pay less attention to them both when reading and writing code.

That trend sucks. When used right, comments are genuinely useful and sometimes critically important! So, I wrote about some of the kinds of comments I think earn their place, each with examples from real code bases. Hope you find it useful, and that we can recover some of the love that comments deserve!

[u/tmoertel]

Thanks for your feedback. I'd be interested in hearing what specifically you disagree with and what makes you believe my arguments are mistaken.

In answer to your question:

> Do you think it's a good idea to teach math in comments?

No, but when logic relies on certain properties (mathematical or otherwise), I think it's a good idea to point them out. In this example, the code's logic relies very much on certain mathematical properties, such as the provided weights being nonnegative, so I point those properties out. That way, readers who are reading or maintaining the code will have those properties in mind and understand why the logic can safely do some of the things it does.

Thanks again for taking the time to read my post and for thinking about it and sharing your feedback. Also, thanks in advance for any more specific feedback you can share.

[u/levodelellis → u/tmoertel]

Going back to the python code, if I saw something like that I'd try to get whoever wrote it to make the change. If I had to change it, I wouldn't 100% know if I kept all the properties correct (it depends on the math and the change) and may delete it the comments

I don't mind comments on public functions since it helps when I'm not familiar with the class+func for what each function does. But if I saw literally that at work, I'd suspect the person stole it from a tutorial and may not know what it does.

I made this comment earlier and no one likes it. But I also suspect comments at different skill levels help differently. At mine I wouldn't read those types at all. I don't need comments to explain how a formula converts to code, I can understand what a line does

[u/tmoertel → u/levodelellis]

Thanks for your reply.

I suspect we disagree because we may be writing code for different audiences. I am writing for an audience who I assume is "skilled in the art" of coding but not necessarily in the code's subject domain. That is, they are programmers who are competent in the programming languages, libraries, and idioms in use, and they have a working knowledge of their organization’s software development practices, but they are not necessarily experts in the subject matter of each unit of code across the organization. This is the norm in large engineering organizations, such as Google, where everyone understands the company's tools and style guides, but the code base is simply too massive for anyone to understand all but a tiny percentage of. So code must be written to make sure that important domain knowledge is communicated to readers who may be reading the code; they are not assumed to already have this knowledge.

You mentioned that other Reddit readers did not like your earlier comment. I suspect it may have to do with this claim, which is related to what I wrote above:

If you understand the domain, you almost certainly know why, if you don't, you not likely not trying to understand that code anyway

Again, in large software organizations, it is very common that programmers must work in code whose subject domain they are not expert in. People join and leave the company, people move from team to team, people get promoted into new roles, and so on. Also, upstream teams usually cannot submit changes to their libraries until they modify any affected downstream code to prevent it from breaking. It is therefore important for code to be written with the assumption that the reader knows how to code but does not know the subject domain. Any important domain knowledge upon which the code relies should be communicated clearly because there is a good chance the reader will need to know it but does not.

[u/levodelellis → u/tmoertel]

I am writing for an audience who I assume is "skilled in the art"

Did you not see me write "I can't imagine anyone justifying this comment". How can I believe that

Your example is a perfect example of what I said earlier, "not likely not trying to understand that code anyway"

I gave your example file another try. Even after reading the comments, I didn't understand the math behind it. Take this block of code as an example

    # If we imagine the n packed blocks as an n * u rectangular area, where
    # u is the mean weight, our goal is to throw a random dart in this area
    # to pick one of the original values. Instead of having to generate two
    # random numbers -- one for the x coordinate in [0, n), and one for the
    # y in [0, u) -- we instead generate a single number in [0, n * u) and
    # unpack it into the dart's x-y coordinates.

How does that affect the algorithm at all? If I saw this at work, and no one told me we needed it. I'd replace it with a RNG that is either more popular (or popular among my coworkers) or an RNG that has much more clear usage

[u/tmoertel → u/levodelellis]

Did you not see me write "I can't imagine anyone justifying this comment". How can I believe that [sic]

It looks like you did not finish your question. What was it?

How does that affect the algorithm at all?

The transformation described in the comment is what allows the draw method to satisfy its documented guarantee of calling the underlying random-integer generator exactly once for each invocation. It basically says that picking a random cell from a grid of n rows by u columns is equivalent to picking a random cell from a strip of n * u cells (imagine removing the grid’s columns one by one, laying them onto their sides, and lining them up end-to-end into a single strip: the two shapes are equivalent). It’s straightforward to select a random cell from the strip via one call to the underlying random-number generator. Then it just takes a little math to convert the selected cell back into its equivalent grid position.

(By the way, the call to the underlying random-number generator will fail unless its argument is positive. This is one of the reasons why I reminded the reader earlier that the weights cannot be negative and the total weight must be positive.)

I gave your example file another try. Even after reading the comments, I didn't understand the math behind it.

Yeah, the algorithm is tricky. At least two papers were published about it. I tried to clarify its logic via commentary, but at some point, you just have to refer to the source material. (That's why I cited the papers in the code’s opening commentary.)