potiuk commented on PR #29489: URL: https://github.com/apache/airflow/pull/29489#issuecomment-1427050501
> This comment not for this test rather than situation with tests in general. > > I thought that is also a good idea to add docstring to tests cases, when we introduce new test case. When I tried to migrate some old tests from unittests to pytest I found that I have no idea what some test about Well I think if we have a need to add docstring to a more than a handful of very specific cases that need a lot of context, then I believe that this is rather an indication that either: a) test code is too complex and should written in better "Descriptive and meaningful" way (see https://enterprisecraftsmanship.com/posts/dry-damp-unit-tests/) discussion or b) test name or corresponding parameterized entries are not descriptive enough IMHO name of the method of the test case (even if its 100 characters) should be descriptive enough to describe what the test is about. This is, I think, far better than docstring. If anything then I'd say in-line comments describing more context of particular lines of the test code are much, much better than test docstrings when the code is not enough to figure out context. As I see it, the docstrings are really useful when you have an API-kind-of-class that you want people use without really having to loook at the code. Docstrings have huge potential of becoming out-dated and invalid, where the code is always doing what it is doing and what it tells. Usually code is far better of a documentation than the documentation itself (or it should be - and we should strive for it). Test code should be distincly different than "production code" as well - less DRY, more descriptive, and it is main property is that it is supposed to be read by whoever who wants to do with it. So it's better if the code speaks to whoever looks at it rather than docstring. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
