3 ms·

If I encountered anyone actually calling that function and seriously wondering what "title" could refer to, my reaction would be to call an ambulance, because t

If I encountered anyone actually calling that function and seriously wondering what "title" could refer to, my reaction would be to call an ambulance, because they're clearly in the midst of a stroke. Comments do not exist to explain basic everyday concepts, nor basic linguistic skills. You might as well ask "what's a CD?".

MaulingMonkey 13y ago
You assume "addCD" actually adds a CD to, say, a music library, rather than being a butchery of "addToCD". This might be unlikely in Java, but if this were C89 (where no function has a containing class and where no parameter based overloading is possible), I'd be calling you the ambulance if you weren't seriously wondering whether "CD" refers to what's being added to, or what's being added.
- nknighthb 13y ago
  Bad names are bad code, and comments are not an excuse for bad code. There's also no reason to believe someone with byzantine naming practices is going to be any better at documentation anyway. And why would a function for adding to a CD have an integer parameter named "tracks"? (If your next argument is "maybe it's for the track number"... Bad name! Bad code!) Finally, context is important, and considering a single function in isolation and thinking up all the ways in which it might be ambiguous (though I've yet to see anyone identify a plausible way in which this one could possibly be) is ridiculous. In all likelihood, the behavior of a function is even more obvious in the overall context of the system/API it's part of.
  - MaulingMonkey 13y ago
    And I don't meant to suggest papering over bad naming conventions with comments. You're preaching to the choir there. What I do mean to suggest is that while in any half decent codebase, addCD should be unambiguous, someone thinking title is ambiguous isn't having a stroke -- at worst they're being incredibly jaded. API design is nontrivial, people make mistakes in the trivial cases distressingly often (due to laziness, lack of familiarity, wildly different backgrounds, or any number of other reasons), and relying on context too much has it's own problems anyways. For example: We're missing it in the very snippet we're discussing. There's no class shown. You're filling in the blanks with reasonable code. I've seen far too much unreasonable code to dismiss it when talking coding styles, and even reasonable code is only a botched refactoring or two away from being unreasonable.

MaulingMonkey 13y ago

You assume "addCD" actually adds a CD to, say, a music library, rather than being a butchery of "addToCD". This might be unlikely in Java, but if this were C89 (where no function has a containing class and where no parameter based overloading is possible), I'd be calling you the ambulance if you weren't seriously wondering whether "CD" refers to what's being added to, or what's being added.

nknighthb 13y ago
Bad names are bad code, and comments are not an excuse for bad code. There's also no reason to believe someone with byzantine naming practices is going to be any better at documentation anyway. And why would a function for adding to a CD have an integer parameter named "tracks"? (If your next argument is "maybe it's for the track number"... Bad name! Bad code!) Finally, context is important, and considering a single function in isolation and thinking up all the ways in which it might be ambiguous (though I've yet to see anyone identify a plausible way in which this one could possibly be) is ridiculous. In all likelihood, the behavior of a function is even more obvious in the overall context of the system/API it's part of.
- MaulingMonkey 13y ago
  And I don't meant to suggest papering over bad naming conventions with comments. You're preaching to the choir there. What I do mean to suggest is that while in any half decent codebase, addCD should be unambiguous, someone thinking title is ambiguous isn't having a stroke -- at worst they're being incredibly jaded. API design is nontrivial, people make mistakes in the trivial cases distressingly often (due to laziness, lack of familiarity, wildly different backgrounds, or any number of other reasons), and relying on context too much has it's own problems anyways. For example: We're missing it in the very snippet we're discussing. There's no class shown. You're filling in the blanks with reasonable code. I've seen far too much unreasonable code to dismiss it when talking coding styles, and even reasonable code is only a botched refactoring or two away from being unreasonable.