7 ms·

This is a classic case of a 'why' code comment being needed. It's obvious what you're doing, but without a 2 line explanation, it's not clear why.

kentonv 6y ago
Yeah I probably wrote that comment the first few times I did this but it's hard to write it the 50th time. Maybe I should have my own tolower() function that I can call so I only have to write the comment once but it just feels ridiculous somehow.
- Natsu 6y ago
  It's far more ridiculous to repeat yourself over and over instead of making a simple function that describes exactly what you want and why.
- random314 6y ago
  Why does it feel ridiculous?
  - kentonv 6y ago
    Because I've already rewritten more of the standard library than is healthy. I mean, it's clearly the right thing to do here but I can predict the conversation that will inevitably result... "You wrote your own tolower() function? Why?" "The standard one is horribly broken." "How could a function that lower-cases a letter be broken??? Jesus Kenton your NIH syndrome is out of control." "Sigh..." (Slightly more seriously, any particular time I need to lower-case something, it takes 10 seconds to write out the code, but would take 10 minutes to find a good place to define a reusable function and exactly what its API should be, and so it never seems worth the effort in the moment. Just like how most messy code comes to be.)
    - nitrogen 6y ago
      Most codebases I've worked with have a StringUtils.java, or .kt, or a str.c or utils.c. Maybe just start one. Interestingly I haven't needed it as much in Ruby. But I too feel the cognitive (and social!) burden of introducing a new function. It's not just "where do I put this", but "how do I convince the team I know what I'm doing since 15 years of experience clearly isn't enough and developers (mostly rightly) ignore positional authority and seniority".
    - random314 6y ago
      This conversation can be simply be avoided by copy pasting your original hacker news comment into the library function header. I have noticed some coworkers have their ego gratified by being right while everyone else is wrong. Instead of simply explaining what they are doing when they are doing it, they will do something that looks wrong in a very noticeable way and wait for the backlash. The backlash gives them an opportunity to show everyone else how they were right while everyone else was wrong and also an opportunity to play victim. However, in SW development - it is not just the technical details - your behavior also matters in a big way. In this particular case, the correct approach is to create your own library function with appropriate comments. This is why the concept of a library function was invented. It is its entire raison-d'etre. However, you are doing everything but that. Including providing justifications in hacker news comments instead of your source code. Now inevitably, someone will change your inline code to use to_lower. This will give you an opportunity to scream bloody murder, show how other engineers don't really understand technical details, correct them and also play victim. Create a library utility with comments and link it in - End of story.
      - kentonv 6y ago
        Speaking of people wanting to gratify their ego by being right: Everyone on this thread trying to lecture me on software engineering? ¯\_(ツ)_/¯
        random314 6y ago
        At least, you get to play victim :)
      - saagarjha 6y ago
        I’m reminded of garbage collector blog posts where they do something stupid (“disable it”, “allocate a ballast”) and then get to spend a couple pages explaining why it worked for them.
    - obmelvin 6y ago
      Looks like you're only 10 times away from using this to having spent your 10 minutes ;) But seriously, I'm not here to lecture you, but personally I'd appreciate having a teammate educate me on the undesired behavior and have a nice function I could use to ensure my own code doesn't break user input
- eitland 6y ago
  Write the function, comment it! Many of these are obvious to many people here, but some aren't. Even I can admit that some of the stuff in this thread is not obvious at all.
- Izkata 6y ago
  #include <kentonv.h>
  - kentonv 6y ago
    It's... It's called KJ... https://github.com/capnproto/capnproto/tree/master/c++/src/kj https://github.com/capnproto/capnproto/tree/master/c++/src/k...
    - lathiat 6y ago
      This project has the greatest sales pitch I've ever seen: https://github.com/capnproto/capnproto/blob/master/README.md https://github.com/capnproto/capnproto/blob/master/README.md -- combined with the project name it's just perfect.
- viraptor 6y ago
  > but it's hard to write it the 50th time. You know you wrote it 49 times before, but the person reading the code probably doesn't. It only changes your experience not everyone else's. If it's the same codebase, just write that function :)
dmurray 6y ago
Seems like it would be even better to put this in its own function with a descriptive name, ascii_tolower or roman_tolower or whatever, that has exactly the semantics you want.
- eitland 6y ago
  Still warrants a comment to be sure no one concludes the built in is good enough.
  - randomdata 6y ago
    It certainly warrants a test to document what the function is for. And if that test also happens to validate that the documentation is accurate, that is a nice side benefit.
    - h0l0cube 6y ago
      > It certainly warrants a test to document what the function is for. You might be being serious, so I'll indulge. How would a test that will never break, for a function that would never be changed (because look at it), that lives in a different part of the directory structure, be worth even one second extra time or thought to write it, over-and-above the descriptive comment that is longer than the code itself, and lives discoverably right next to the code itself?
      - xahrepap 6y ago
        I've found that writing a unit test to verify it works at all is sometimes loads easier than manually running the app or whatever. At that point, just leave the test and check it in.
        h0l0cube 6y ago
        I agree with this, kind of. Though I've found that keeping useless tests around doesn't always have 0 cost, same for any dead code. Often, though, you can verify that your code works using a REPL. I'm also a huge fan of how doc-tests in some languages that make the tests are part of the documentation, and neatly 'cohere' them to the function itself. At which point I'm happy to leave them in, as the tests-as-documentation are harder to miss, and are actually instructive.
lmm 6y ago
Comments are unreliable, you should use tooling to fix this forever. E.g. findbugs has a rule for this problem: http://findbugs.sourceforge.net/bugDescriptions.html#DM_CONVERT_CASE http://findbugs.sourceforge.net/bugDescriptions.html#DM_CONV...

kentonv 6y ago

Yeah I probably wrote that comment the first few times I did this but it's hard to write it the 50th time. Maybe I should have my own tolower() function that I can call so I only have to write the comment once but it just feels ridiculous somehow.

Natsu 6y ago
It's far more ridiculous to repeat yourself over and over instead of making a simple function that describes exactly what you want and why.
random314 6y ago
Why does it feel ridiculous?
- kentonv 6y ago
  Because I've already rewritten more of the standard library than is healthy. I mean, it's clearly the right thing to do here but I can predict the conversation that will inevitably result... "You wrote your own tolower() function? Why?" "The standard one is horribly broken." "How could a function that lower-cases a letter be broken??? Jesus Kenton your NIH syndrome is out of control." "Sigh..." (Slightly more seriously, any particular time I need to lower-case something, it takes 10 seconds to write out the code, but would take 10 minutes to find a good place to define a reusable function and exactly what its API should be, and so it never seems worth the effort in the moment. Just like how most messy code comes to be.)
  - nitrogen 6y ago
    Most codebases I've worked with have a StringUtils.java, or .kt, or a str.c or utils.c. Maybe just start one. Interestingly I haven't needed it as much in Ruby. But I too feel the cognitive (and social!) burden of introducing a new function. It's not just "where do I put this", but "how do I convince the team I know what I'm doing since 15 years of experience clearly isn't enough and developers (mostly rightly) ignore positional authority and seniority".
  - random314 6y ago
    This conversation can be simply be avoided by copy pasting your original hacker news comment into the library function header. I have noticed some coworkers have their ego gratified by being right while everyone else is wrong. Instead of simply explaining what they are doing when they are doing it, they will do something that looks wrong in a very noticeable way and wait for the backlash. The backlash gives them an opportunity to show everyone else how they were right while everyone else was wrong and also an opportunity to play victim. However, in SW development - it is not just the technical details - your behavior also matters in a big way. In this particular case, the correct approach is to create your own library function with appropriate comments. This is why the concept of a library function was invented. It is its entire raison-d'etre. However, you are doing everything but that. Including providing justifications in hacker news comments instead of your source code. Now inevitably, someone will change your inline code to use to_lower. This will give you an opportunity to scream bloody murder, show how other engineers don't really understand technical details, correct them and also play victim. Create a library utility with comments and link it in - End of story.
    - kentonv 6y ago
      Speaking of people wanting to gratify their ego by being right: Everyone on this thread trying to lecture me on software engineering? ¯\_(ツ)_/¯
      - random314 6y ago
        At least, you get to play victim :)
    - saagarjha 6y ago
      I’m reminded of garbage collector blog posts where they do something stupid (“disable it”, “allocate a ballast”) and then get to spend a couple pages explaining why it worked for them.
  - obmelvin 6y ago
    Looks like you're only 10 times away from using this to having spent your 10 minutes ;) But seriously, I'm not here to lecture you, but personally I'd appreciate having a teammate educate me on the undesired behavior and have a nice function I could use to ensure my own code doesn't break user input
eitland 6y ago
Write the function, comment it! Many of these are obvious to many people here, but some aren't. Even I can admit that some of the stuff in this thread is not obvious at all.
Izkata 6y ago
#include <kentonv.h>
- kentonv 6y ago
  It's... It's called KJ... https://github.com/capnproto/capnproto/tree/master/c++/src/kj https://github.com/capnproto/capnproto/tree/master/c++/src/k...
  - lathiat 6y ago
    This project has the greatest sales pitch I've ever seen: https://github.com/capnproto/capnproto/blob/master/README.md https://github.com/capnproto/capnproto/blob/master/README.md -- combined with the project name it's just perfect.
viraptor 6y ago
> but it's hard to write it the 50th time. You know you wrote it 49 times before, but the person reading the code probably doesn't. It only changes your experience not everyone else's. If it's the same codebase, just write that function :)

dmurray 6y ago

Seems like it would be even better to put this in its own function with a descriptive name, ascii_tolower or roman_tolower or whatever, that has exactly the semantics you want.

eitland 6y ago
Still warrants a comment to be sure no one concludes the built in is good enough.
- randomdata 6y ago
  It certainly warrants a test to document what the function is for. And if that test also happens to validate that the documentation is accurate, that is a nice side benefit.
  - h0l0cube 6y ago
    > It certainly warrants a test to document what the function is for. You might be being serious, so I'll indulge. How would a test that will never break, for a function that would never be changed (because look at it), that lives in a different part of the directory structure, be worth even one second extra time or thought to write it, over-and-above the descriptive comment that is longer than the code itself, and lives discoverably right next to the code itself?
    - xahrepap 6y ago
      I've found that writing a unit test to verify it works at all is sometimes loads easier than manually running the app or whatever. At that point, just leave the test and check it in.
      - h0l0cube 6y ago
        I agree with this, kind of. Though I've found that keeping useless tests around doesn't always have 0 cost, same for any dead code. Often, though, you can verify that your code works using a REPL. I'm also a huge fan of how doc-tests in some languages that make the tests are part of the documentation, and neatly 'cohere' them to the function itself. At which point I'm happy to leave them in, as the tests-as-documentation are harder to miss, and are actually instructive.

lmm 6y ago

Comments are unreliable, you should use tooling to fix this forever. E.g. findbugs has a rule for this problem: http://findbugs.sourceforge.net/bugDescriptions.html#DM_CONVERT_CASE http://findbugs.sourceforge.net/bugDescriptions.html#DM_CONV...