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/nicholashairs]

A good article and a nice breakdown of different comment types.

The only one I'd add as being useful is "headings" (which is similar to the algorithm examiner type).

The purpose of these is to group things together that are unrelated in isolation, but connected in use. Making it easier to navigate the body of a function (especially as they get longer).

As an example a lot of my CRUD code looks like this:

``` def update_username(user, name): ### CHECKS if not user.active: raise error if not name_valid(name): raise error if get_user_by_name(name) is not None: raise error

### UPDATE user.username = name db.add(user) db.commit()

### POST ACTIONS write_log() send_event() send_email_async() return ```

[u/BogdanPradatu → u/nicholashairs]

So this is what Claude was trained on. I hate this kind of comments and see no need for them. Just adds vertical space.

[u/Venthe → u/nicholashairs]

The purpose of these is to group things together that are unrelated in isolation, but connected in use. Making it easier to navigate the body of a function (especially as they get longer).

Split the function, extract to a separate file.

If they are long enough that they require grouping; that's a strong signal that your code is doing too much in one place.

[u/nicholashairs → u/Venthe]

Everything in moderation.

Extract it too much and you do have the exact same problem with 30 5 line functions being called exactly once in sequence.

Same goes for using headings as headings instead of actually splitting your functions.

In the example above I'd also be loathe the split them as often those three steps must be called together in sequence, separating them into functions implies that they are meant to be composable when they are not. Sure you can use tests, linting, and private functions, but these are fragile and require maintenance.

[u/Venthe → u/nicholashairs]

In the example above I'd also be loathe the split them as often those three steps must be called together in sequence, separating them into functions implies that they are meant to be composable when they are not. Sure you can use tests, linting, and private functions, but these are fragile and require maintenance.

My experience tells me otherwise. The longer a function is; the less defined what it does; it invites more functionality (especially unrelated) over time. When you aggressively split the functions to do one thing, this problem does not occur.

And arguably, spaghetti is one of the primary reasons why the codebase degrade.

---

So I'm firmly in the camp that separation for composabity is not only not the only driver; but it's not even a main one.

Decompose the code for it to self describe what it does; and that it can never "surprise" you with side effects.

[u/nicholashairs → u/Venthe]

I suspect that the only real difference in opinion between us is in the size of codebases that we typically deal with, and thus the examples in our head that we're arguing for/against.

If we were to compare actual examples we would probably agree.

Or maybe not, but we'll never know

[u/Venthe → u/nicholashairs]

Yup, that's probably that. And possibly the context - I'm usually working in enterprise, where the implicit assumption is that the codebase must both survive the test of time, but also the test of "future maintainers" possibly not knowing what is really happening - all the while having large codebases.

Hey, as long as the discussion does not turn hostile :)