What’s the alternative? Write an inline sort routine 30 times?
I’m not so sure the example is particularly good. Assuming the sort is just a one line call to a library routine, then the comment would be unnecessary. You call the API, then you sort the results and it should be obvious to any maintenance programmer why. Don’t comment obvious stuff.
If you are doing this 30 times, then put the API call and the sort in a subroutine called callApiAndSort().
The suggestion was that a comment be used when the reason for the sort was not obvious. Not that every sort be commented to explain why. So there’s no reason why you’d wrap every sort call in a custom subroutine either.
The alternative is to just call the sort function and add a comment if the reason why it’s being sorted isn’t obvious rather than making a new function so that the function name can act as the comment.
I just see “never do x, no exceptions” as overly constraining yourself when sometimes a comment might be a better option than jumping through a hoop that involves having a function named “sortRandomAPIResults” just to avoid ever using a comment. Even goto statements have cases where you get better code from just using goto than everything required to avoid it.
Better to understand the purpose of the thing you are doing and to be aware of the pitfalls using it might subject you to. Yeah, there are a ton of comments out there that are useless or even misleading, but there are helpful ones, like if a function encodes some data for some specific spec, a comment that includes information about that spec can help. Like url for documentation, or a description of the relevant fields it’s filling in. Yeah, you could get that from data structures and looking at the code, but it’s a bit more mental effort to do that, plus it assumes the code is correctly doing what the programmer intended it to do.
If some code looks very close to some standard math thing but is slightly different, is that a bug, a way that this case differs from the usual case, or an optimization? Iirc Carmack introduced some optimisations for 3d rendering doom that even he wasn’t fully aware of how they worked, just that they were able to test the output over the range of relevant inputs and determined that it always gave a solution that was good enough to be able to skip some slower method that was easier to understand.
And there’s also language barriers. Some code that looks very descriptive to you might not be so obvious to someone who isn’t a native speaker or even just has sufficient cultural differences to not pick up on a reference. I’d bet that translation tools, that don’t always do great at translating meaning rather than words, will struggle even more if that meaning is encoded in C++ as well as English.
Hard and fast rules are for beginner, but their code is going to be crap anyway.
For everyone else, comments when it makes the most sense is all you need.
I will say that following a few simple principles, when appropriate, like “Don’t Repeat Yourself”, and the “Single Responsibility Principle” tend to lead to smaller methods with clear intent that give better opportunities to name things appropriately.
If I see well laid out code with one or two comments, I’m likely to actually read the comments. Otherwise I view comments as meaningless noise.
What’s the alternative? Write an inline sort routine 30 times?
I’m not so sure the example is particularly good. Assuming the sort is just a one line call to a library routine, then the comment would be unnecessary. You call the API, then you sort the results and it should be obvious to any maintenance programmer why. Don’t comment obvious stuff.
If you are doing this 30 times, then put the API call and the sort in a subroutine called callApiAndSort().
The suggestion was that a comment be used when the reason for the sort was not obvious. Not that every sort be commented to explain why. So there’s no reason why you’d wrap every sort call in a custom subroutine either.
The alternative is to just call the sort function and add a comment if the reason why it’s being sorted isn’t obvious rather than making a new function so that the function name can act as the comment.
I just see “never do x, no exceptions” as overly constraining yourself when sometimes a comment might be a better option than jumping through a hoop that involves having a function named “sortRandomAPIResults” just to avoid ever using a comment. Even goto statements have cases where you get better code from just using goto than everything required to avoid it.
Better to understand the purpose of the thing you are doing and to be aware of the pitfalls using it might subject you to. Yeah, there are a ton of comments out there that are useless or even misleading, but there are helpful ones, like if a function encodes some data for some specific spec, a comment that includes information about that spec can help. Like url for documentation, or a description of the relevant fields it’s filling in. Yeah, you could get that from data structures and looking at the code, but it’s a bit more mental effort to do that, plus it assumes the code is correctly doing what the programmer intended it to do.
If some code looks very close to some standard math thing but is slightly different, is that a bug, a way that this case differs from the usual case, or an optimization? Iirc Carmack introduced some optimisations for 3d rendering doom that even he wasn’t fully aware of how they worked, just that they were able to test the output over the range of relevant inputs and determined that it always gave a solution that was good enough to be able to skip some slower method that was easier to understand.
And there’s also language barriers. Some code that looks very descriptive to you might not be so obvious to someone who isn’t a native speaker or even just has sufficient cultural differences to not pick up on a reference. I’d bet that translation tools, that don’t always do great at translating meaning rather than words, will struggle even more if that meaning is encoded in C++ as well as English.
Hard and fast rules are for beginner, but their code is going to be crap anyway.
For everyone else, comments when it makes the most sense is all you need.
I will say that following a few simple principles, when appropriate, like “Don’t Repeat Yourself”, and the “Single Responsibility Principle” tend to lead to smaller methods with clear intent that give better opportunities to name things appropriately.
If I see well laid out code with one or two comments, I’m likely to actually read the comments. Otherwise I view comments as meaningless noise.