5 ms·
We don't need to put this much responsibility on test names. If there is more to explain, write a few words in a comment.
by BurningFrog 6y ago
We don't need to put this much responsibility on test names. If there is more to explain, write a few words in a comment.
- exdsq 6y agoYou don’t see comments in a test report though — maybe have an optional description as part of the framework for more detail along with -v
- munchbunny 6y agoI think this is one of those conventions where your team agrees on one convention, and you just try to follow it consistently. If that's looking at the test in code to find descriptive comments, great. If that's long test names, cool. Just do the same thing consistently.
- exdsq 6y agoTrue - I think it depends on who uses your test outputs. If PMs and BAs care, having a more verbose output (descriptions, pretty graphs, etc) helps a lot. If it’s just for devs then they can more happily go through the code base.
- nerdponx 6y agoI know that the docstring in Unittest is part of the reported output, and I was pretty sure that it's the same in Pytest.
- masklinn 6y agoI would've thought so but no, pytest will show the docstring in `--collect-only -v` (badly), but it doesn't show any sort of description when running the tests, even in verbose mode (see issue #7005 which doesn't seem to be very popular)
- masklinn 6y ago`unittest` prints the docstring alongside the name of the test in verbose mode (e.g. failure). pytest does not though.
- mumblemumble 6y agoI'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 agoI 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 agoMy 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 agoThat'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 agoAll 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.
- stinos 6y agoIt's a choice of course, but I look at test functions like other functions. If you can name a function such that it doesn't need a comment (but also doesn't use 100 characters to do that), I'll gladly take that over a comment. Same like in all other code: if you need comments to explain what it does, it's likely not good enough and/or needs to be put in a function which tells what it does. Comments on why it does stuff the way it does are of course where it's at.
- xapata 6y agos/comment/docstring/
- BurningFrog 6y agoI have yet to understand the point of docstrings. How are they, in practical reality, better than comments?
- powersnail 6y agoThe difference is in tooling. Docstrings are collected and displayed in many contexts. The intended purpose is writing “documentation” in the same place as code. Comments are only seen if you open the source file.
- BurningFrog 6y agoOK, I can see how that's useful for a certain workflow. The way we work, it's just a different comment syntax. I do like have a dedicated place for it.
- xapata 6y agoPython's builtins, the standard library, and many popular community libraries and tools use docstrings to generate tooling and documentation websites. Describing it as "useful for a certain workflow" is so understated it borders on false. The reverse is more true: docstrings are not useful for a certain workflow, but most Python programmers will find them quite helpful. All Python programmers already benefit from the docstrings written in the libraries they use, which generate tooltips and documentation websites.
- f00_ 6y agoyou can access it from object.__doc__, and there is tooling in ide's like pycharm to quick view them to see what a function does, auto generated documentation prior to mypy/type hints it allowed you to document the types of a function