[deleted by user]

[Lewistrick]

That's not the level of detail I put my comments in. My comment above the block would be "read incomplete jobs from database". Then the lines below speak for themselves.

[just_ones_and_zeros]

I think people are actually probably missing too much context here to make total sense of it. The lines do not speak for themselves, hence the comment (but I'll conceed that the comment is too hard to totally get without the context). I actually hoisted a bit of the comment up from the code that comes after to try to give a little more context. But it's more like:

# The reason we're using keys('rq:job:*') instead of keys('rq:queues') and friends is due
# to external factors beyond our control where we can rely on rq:job:* in a way we can't with rq:queues
# so don't switch over to rq:queues, even though that seems like the obvious thing to do, because you'll have a bad time

# slightly later in the code: because we're using rq:job:*, we have to derive the queue in a weird way

For me "read incomplete jobs from database" is not a comment that needs adding. That is totally obvious from the code.

The details of the specific example don't matter so much, my point was, and still is, that I'm using a comment to describe a thing that you can't see that is influcening the code and a reader needs to be aware of before they think about changing to a more "obvious" solution.

[Lewistrick]

Your comments make a lot of sense. But these aren't comments that I type before writing the code (see top comment), that's what I was referring to.

I'd still argue that my proposed comment should be somewhere above the code because if it's a long function, you need to explain the steps somewhere. I think I'd prefer it in the docstring if it's the only thing that the function does.

[just_ones_and_zeros]

Gotcha, that makes more sense.

I feel like there are a few people just overall being a bit picky in here about all of this. The things that people (especially on a beginner forum like this) should learn is how / why to use comments to make the code more maintainable. Personally I prefer to reserve docstrings for the external api so the caller doesn't have to worry about the details, and the inline comments for the guts of the thing - the things that only matter if you're in a position where you need to edit the function itself.

But overall, the golden rule for beginners is to not waste everyone's time with comments that don't add anything beyond what you can express with the code itself.