5 ms·

I've just never seen the "this belongs in comments" approach work out in practice. Maybe it's something about human psychology. Perhaps things might seem obviou

I've just never seen the "this belongs in comments" approach work out in practice. Maybe it's something about human psychology. Perhaps things might seem obvious when you've just written the test, so you don't think to comment them. Perhaps code reviewers feel less comfortable saying, "I don't understand this, could you please comment it?" Perhaps it's the simple fact that optional means optional, which means, "You don't have to do it if you aren't in the mood." Regardless of the reason, though, it's a thing I've seen play out so many times that I've become convinced that asking people to do otherwise is spitting into the wind.

rbanffy 6y ago
I really hate, but I can see its virtue, the pylint rule that complains about lacking docstrings. In tests, however, I prefer not to have them as my favorite test runners replace the full name of the test method with its docstring, which makes it a lot harder to find the test in the code.
- ben509 6y ago
  My only issue is that the rule doesn't give you a good way to annotate that the object is documented by its signature. Sometimes devs are lazy, but the rule doesn't make them not lazy so you get pointless docs like: def matriculate_flange(via: Worble): "Matriculates flange via a Worble."
  - rbanffy 6y ago
    That's more or less why I hate this feature - it encourages lazy docstrings. Right after you named something is probably the worst possible time for you to explain it.
BurningFrog 6y ago
All this is true, but doesn't it apply just as much to writing descriptive test function names? Test function names are less sensitive than regular functions, since they're not explicitly called, but I still don't want to read a_sentence_with_spaces_replaced_by_underscores.
- mumblemumble 6y ago
  I don't want to either, but until Python gives us backtick symbols or we something like Kotlin's kotest that lets the test name just be an actual string, that's sort of the choice we're left with. And I'm inclined to take the option that I've known to lead to more maintainable tests over the long run over the option that I've known to engender problems, even if it is harder on the eyes. Form after function. As far as whether or not people do a better job with descriptive test function names, what I've seen is that they do? I of course can't share any data because this is all in private codebases, so I guess this could quickly devolve into a game of dueling anecdotes. But what I've observed is that people tend to take function names - and, by extension, function naming conventions - seriously, and they are more likely to think of comments as expendable clutter. (Probably because they usually are.) Which means that they'll think harder about function names in the first place, and also means that code reviewers are more likely to mention if they think a function name isn't quite up to snuff. And I just don't like to cut those sorts of human behavior factors out of the picture, even when they're annoying or hard to understand. Because, at the end of the day, it's all about human factors.
  - BurningFrog 6y ago
    I don't disagree with much of this. I was talking specifically about a `def test_displays_error_message_when_refresh_times_out()` function. That's too big a name for me to keep in my head, so I'd look for other solutions.
    - atoav 6y ago
      Why would you want to keep test function names in your head? I would rather use that space for regular functions which are in use throughout my program. Test functions are usually single-use anyways so being greedy with characters makes much more sense elsewhere. The most important thing to remember about a test function is what property it tests (and how). Putting that in the function name as a reminder makes a lot of sense imo.
- atoav 6y ago
  I would read that any day over a function called test() where I have to figure out what is actually being tested.
dllthomas 6y ago
I've been speculating that the right place for the "why" of tests to live is in documentation, where references should be hung like citations (which may or may not be included in any given rendering of the documentation in question) supporting claims of fact. Then we can surface that any time a test fails, and find tests that no longer check anything we care about.

rbanffy 6y ago

I really hate, but I can see its virtue, the pylint rule that complains about lacking docstrings. In tests, however, I prefer not to have them as my favorite test runners replace the full name of the test method with its docstring, which makes it a lot harder to find the test in the code.

ben509 6y ago
My only issue is that the rule doesn't give you a good way to annotate that the object is documented by its signature. Sometimes devs are lazy, but the rule doesn't make them not lazy so you get pointless docs like: def matriculate_flange(via: Worble): "Matriculates flange via a Worble."
- rbanffy 6y ago
  That's more or less why I hate this feature - it encourages lazy docstrings. Right after you named something is probably the worst possible time for you to explain it.

BurningFrog 6y ago

All this is true, but doesn't it apply just as much to writing descriptive test function names? Test function names are less sensitive than regular functions, since they're not explicitly called, but I still don't want to read a_sentence_with_spaces_replaced_by_underscores.

mumblemumble 6y ago
I don't want to either, but until Python gives us backtick symbols or we something like Kotlin's kotest that lets the test name just be an actual string, that's sort of the choice we're left with. And I'm inclined to take the option that I've known to lead to more maintainable tests over the long run over the option that I've known to engender problems, even if it is harder on the eyes. Form after function. As far as whether or not people do a better job with descriptive test function names, what I've seen is that they do? I of course can't share any data because this is all in private codebases, so I guess this could quickly devolve into a game of dueling anecdotes. But what I've observed is that people tend to take function names - and, by extension, function naming conventions - seriously, and they are more likely to think of comments as expendable clutter. (Probably because they usually are.) Which means that they'll think harder about function names in the first place, and also means that code reviewers are more likely to mention if they think a function name isn't quite up to snuff. And I just don't like to cut those sorts of human behavior factors out of the picture, even when they're annoying or hard to understand. Because, at the end of the day, it's all about human factors.
- BurningFrog 6y ago
  I don't disagree with much of this. I was talking specifically about a `def test_displays_error_message_when_refresh_times_out()` function. That's too big a name for me to keep in my head, so I'd look for other solutions.
  - atoav 6y ago
    Why would you want to keep test function names in your head? I would rather use that space for regular functions which are in use throughout my program. Test functions are usually single-use anyways so being greedy with characters makes much more sense elsewhere. The most important thing to remember about a test function is what property it tests (and how). Putting that in the function name as a reminder makes a lot of sense imo.
atoav 6y ago
I would read that any day over a function called test() where I have to figure out what is actually being tested.

dllthomas 6y ago

I've been speculating that the right place for the "why" of tests to live is in documentation, where references should be hung like citations (which may or may not be included in any given rendering of the documentation in question) supporting claims of fact. Then we can surface that any time a test fails, and find tests that no longer check anything we care about.