I actually see a legitimate use case for it and helped add the actions version in a project where I'm a collaborator.
Quite a bit, certain bugs disappear after an update without us targeting it (partially because the logs get fudged a bit after going through dependencies, so sometimes multiple bugs have the same cause or it's actually a dependency issue that got fixed) and sometimes we forget about old feature requests.
The stale reminder doubles as a reminder for us to (re)consider working on the issue. When we know something probably isn't gonna get fixed suddenly, we apply a label to the issue. For enhancements that we'll definitely work on soon™, we apply help wanted. We've configured the action to ignore both. We also patrol notifications from stale to see if something shouldn't go stale. This is a medium-sized project so we can handle patrolling and IMO this helps us quite a bit.
Fair enough; I didn’t consider artifacts like logs and traces. I suppose a stale marker might prompt the original reporter to retest and supply fresh ones (or confirm it’s fixed in the dependency case).
In an ideal world I suppose we’d have automated tests for all bug reports but that’s obviously never going to happen!
Comments are lies that will happen sometime in the future
Comments are always overlooked if gode gets refactored. Language servers can’t/won’t parse them and they’re easy to overlook.
If you name your functions/variables clearly, put complex logic into clearly named functions and keep the same level of abstraction in every function (which never exceeds roughly 50 lines), you hardly need any comments, if any.
Comments are for behavior that’s not possible to convey clearly through code.
If a block of code needs a comment, then you can easily move that block into a function and summarise the comment into a name for that function. If you can not easily move a block of code into a function, then you may need to rethink your design.
This isn’t always true of course, but it’s a good mindset to have.
Comments don’t describe the code. They describe the decision to use this business logic.
If you stick to good engineering practices, like small methods/functions, decoupling, and having testable code, you don’t often need many comments to show what your code does. I always recommend a method signature, though, because you can save a few seconds by just saying that a block of code does, rather than me needing to read exactly how you turned one dict into another dict…
I agree for inline code comments, like, “# Save the sprocket”, right above the line that saves the sprocket. Does this include documentation? Because when I see a prepareForSave function that references 10 other functions and I just want to know, “Is this mutating and how is it preparing for save and when should I call it?”, having the author spend 15 seconds telling me is less time consuming than me spending 5 minutes reading code to find out. Anyone who has read API docs has benefited from documentation.
No, commenting a function should be commonplace, if not only so that your IDE/editor can use the documentation when the signature is found elsewhere in your code.
Within a function, though, basically means that something gnarly is happening that wouldn’t be obvious, or that the function is doing more than it (probably) should.
programmer_humor
Top
This magazine is from a federated server and may be incomplete. Browse more on the original instance.