I know some folks are joking about and dunking on this, but in modern times, I have justification. Call me lazy, but I have found myself writing out these comments and then letting the AI take over to at least give me a sketch of an implementation. Works reasonably well and saves me a lot of time and effort. Mostly I don’t bother to remove them, though I usually edit them a bit.
On the other hand, there are factions within my colleagues who steadfastly insist that commenting is unnecessary and to some degree even potentially harmful, and that if you feel the need to comment your code, it means your code should be improved so that it’s obvious what it is doing without the need for comments.
And your colleagues are probably correct with respect to this sort of «what it does» commenting. That can be counterproductive because if the code changes and the comment isn’t updated accordingly, it can be ambiguous. Better have the code be the singular source of truth. However, «why it does it» comments are another story and usually accepted by most as helpful.
I’ll add that you should have a comment anytime you are using some sort of algorithm to explain what it is and the expected result when it’s not intuitive or a complex math operation that isn’t immediately clear.
Ex// I’m using Newton’s Method to approximate a solution to speed up the inverse square root
Would you mind sharing a bit more about the workflow you’re describing? I’m on a “ask people how they’re using AI to help them dev” kick.
Sounds like you’re using an agent integrated with your IDE, would you be willing to give specifics? And you’re talking about writing some comments that describe some code you haven’t yet written, letting the AI take a stab at writing the code based on your comments, and then working from there? Did I get that right?
Happy for literally any elaboration you feel like giving :)
I know some folks are joking about and dunking on this, but in modern times, I have justification. Call me lazy, but I have found myself writing out these comments and then letting the AI take over to at least give me a sketch of an implementation. Works reasonably well and saves me a lot of time and effort. Mostly I don’t bother to remove them, though I usually edit them a bit.
On the other hand, there are factions within my colleagues who steadfastly insist that commenting is unnecessary and to some degree even potentially harmful, and that if you feel the need to comment your code, it means your code should be improved so that it’s obvious what it is doing without the need for comments.
At least docblocking a summary above every method is always good. You can automatically generate documentation this way.
And your colleagues are probably correct with respect to this sort of «what it does» commenting. That can be counterproductive because if the code changes and the comment isn’t updated accordingly, it can be ambiguous. Better have the code be the singular source of truth. However, «why it does it» comments are another story and usually accepted by most as helpful.
I’ll add that you should have a comment anytime you are using some sort of algorithm to explain what it is and the expected result when it’s not intuitive or a complex math operation that isn’t immediately clear. Ex// I’m using Newton’s Method to approximate a solution to speed up the inverse square root
Would you mind sharing a bit more about the workflow you’re describing? I’m on a “ask people how they’re using AI to help them dev” kick.
Sounds like you’re using an agent integrated with your IDE, would you be willing to give specifics? And you’re talking about writing some comments that describe some code you haven’t yet written, letting the AI take a stab at writing the code based on your comments, and then working from there? Did I get that right?
Happy for literally any elaboration you feel like giving :)