10 comments

1. I have also thought about this problem, but overall I think that comments in unit testings are usually unnecessary if the tests are laid out well. Then the unit tests also serve as an in-use documentation of your code. Another developer could easily look at your tests to determine how and what a piece of code does. Long test names therefore become a requirement.

   As an added benefit, most unit testing frameworks will display the test name when said test fails, so a descriptive test name makes the failure more obvious.

   Last, as a practical thought, writing descriptive comments for unit tests can severely increase development time with arguably little benefit.

   LikeLiked by 1 person

   Reply
2. Pingback: Tweets that mention How long is too long (for unit test method names)? at blog.phpdeveloper.org -- Topsy.com

3. I subscribe to the “use descriptive test method names” camp — heck, you quoted two of my tweet replies to you above. 🙂

   My rationale hinges on several points:

   * The test name helps describe the behavior I’m testing. This solves a few problems. First, I can be fairly certain that I have unique method names this way, without having to resort to non-semantic names like testSomeMethod1(), etc. Second, if a failure or error occurs while testing, I can easily cut and paste the name. Third, on same failure, I have an idea of what behavior is failing. During initial development, this is less useful, but later, when I apply a new feature or fix another bug, I can easily grok what I broke in the process.
   * PHPUnit offers “testdox” output. This takes the CamelCasedText of the method name, and spits it out as sentences. This can serve as a nice indication of capabilities that have been explicitly tested.
   * There are enough barriers to testing as it is: you have to understand how to create a test case, how to create test methods, potentially how to scaffold, and more. Why would I require adding docblocks to something that will never even be compiled into API docs? If the methods are well named and describe the behavior under test, what more documentation do I really need?

   Sure, this can lead to some tremendously long names on occasion, but the benefits are very much worth it, in my opinion.

   LikeLike

   Reply

4. My view is that the need for a comment is a failure of my code to not be explicit enough (not clear enough in its intentions and/or naming). In other words, what about the code is unclear such that it requires a comment? Is it doing too much? Is it not granular enough? Why is it not clear from the name what the test does? These are the questions I ask myself when I find myself needing to add a comment to a unit test (or elsewhere, for that matter).

   I tend to adopt a BDD-ish approach for my unit tests (in that I regard them as specifying behavior rather than testing). With that approach, the name is the most important thing about the test. I think the name should be easily understandable to anyone reading it (because it is a specification for the behavior), so length can be an asset rather than a problem there. Of course, if the name is too long, then the test is probably trying to do do more than one thing, but that’s a problem with the test, not with the name. The goal is to have the test be an ‘executable specification’ for the unit (and hence the test names serve ares the’ documentation’ for the unit since they are a complete description of the unit’s behavior).

   PHPUnit’s testdox is a useful check. It’s helpful to just read the testdox output for a class and see if you can understand what the class does. And if the purpose of a particular test isn’t clear from reading its testdox output, then the test probably isn’t very well-focused and is probably just testing what’s there (or testing an implementation) rather than specifying behavior. Just my two cents. Thanks for starting an interesting discussion.

   LikeLike

   Reply

5. What THE FUCK?

   LikeLike

   Reply

6. Ups, again

   What the Fuck? So all the “code mus comment it self” people just go to someone doing the same style and try working through her/his codebase. And then tell me they not wanted to have some comments at one point.
   It’s not about us Pro-People reading this code. Leaving comments might be a nice hint for the inexperienced people reading it or the next generation! How many lines of code (for example cobol) got thrown away just for the reason of beeing undocumented? Respect the others that might not be as badass as you and me and knowing the latest trick on the latest fuction call. There are lots of examples of technical achievements in the history of mankind that are simply left undocumented, for example the pyramids, stonehenge etc. To build something that lasts means making it feasable for usage for a long time. We havent realised this, but what’s happening now is a very fragile revolution. Knowhow (and this is what code basically is) is very temporary now. We are doing things that could run forever (if nicely migrated to new boxes all five years) and we should behave so, the longlivety of our products depends on it. There is no gurantee that the person looking at the piece of code has knowledge or all the docs we have.

   Some stuff that comes up with tests.

   – The Name must be descriptive
   – The name, the function keyword and name should be readable in one shot. What does that mean?
   – You have the Obligation to leave a comment here and there

   Very simple. There is a really different level of literacy around the world and even among us programmers. I am a bad reader, easily distracted often doing more than one thing. So before I am at the last letter of myVeryLongFunctionNameJustBecauseIcanDoItandItsDoingLotOfThings I probably have tried it.

   And then there is this special setup you might have that might not apply to the poor guy sitting in a Web Cafe in a 3rd world country starring at this nice piece of self documenting code on a 12 inch greenscreen with some pixels dead, and he is required to read through: myVeryLongFunctionNameJustBecauseIcanDoItandItsDoingLotOfThings?

   I think now 😉 KISS guys 😉

   p.s. I have patented all the spelling errors 😉

   LikeLike

   Reply

7. I tend to write unit test method names that run parallel to what it is testing:

   testSomeFunction might be the normal case for someFunction
   testSomeFunctionWithBadXCausesException saying that I am passing something bad and expect an exception
   testSomeFunctionForRegressionBug3456 saying that this test is for a specific bug report

   and so on . . .

   LikeLike

   Reply

8. Thanks for the post Chris… Now to address some more things that would not fit into 140 characters 🙂

   PHPUnit does use some docblocks to handle certain conditions and more (see the annotations section): http://www.phpunit.de/manual/current/en/appendixes.annotations.html

   Creating actual docblocks for writing out the test may be nice in terms of creating PHPDoc but it may be a bit of extra overhead that will not add too much value since the structure of your tests should match the structure of your application. With this – it is easy to know what failed then by the method name you should have an extremely good idea of what had failed.

   From there, it is really the job of a CI server to take all of the different types of output and aggregate them for you. For instance we run the following:
   * PHPMD (Mess Detector)
   * PHPCPD (Copy Paste Detector)
   * PHP Depend (Quality of Design)
   * PHPUnit w/ Clover Output

   A bunch of other misc items as well. The test names are more or less descriptive of what broke where as I don’t need to look through 500 things to figure it out.

   LikeLike

   Reply

9. I have not read the comments here very thoroughly, but here is an approach I tend to like:

   The tests are namespaced, the name is generalized and then given a sequence number to group related tests. For example:

   Mail.Transport.Send_001
   Mail.Transport.Send_002
   Mail.Transport.Receive_001

   ..and so on. Whenever I can, I incorporate symbolic names from specifications if any.

   The test code must documented in a clear and concise manner (important!), and I then use phpdoc, javadoc, SandCastle or whatever is at hand to generate test code documentation *before* I execute the tests.

   I then place my test harness on one monitor, and test code documentation on the other, and press play. If anything fails, I only need to glance at the documentation to know who’s ass I need to whip (usually my own).

   The reasons for doing this:
   * I am absolutely no fan of the “myVeryLongFunctionNameJustBecauseIcanDoItandItsDoingLotOfThings” — it’s hard to read, hard to remember, and the “form” is difficult to recognize by a glance
   * The short names with sequence numbers are surprisingly simple to learn and remember, much more so than long and very descriptive names
   * It looks neat and professional in a test report, or when correlated in a specification

   Just my two cents, there are lots of other good advices here!

   LikeLike

   Reply

10. Just want to share of what I currently used to name my unit test methods.

    My formula/template for naming unit test method is “WHEN_[condition]_SHOULD_[behave]”. This formula suit my needs cause it’s describe the behavior of unit under test. I got these formula after watching Roy Osherove presentation video. This naming strategy can produce a very long but descriptive name. I don’t use the “test” prefix cause it’ll make my already long name longer. And, PHPUnit provide annotation substitute with “@test”. Here is an example of what’s on my unit testing.

    /** @test */
    function WHEN_checking_validity_of_attribute_that_have_invalid_value_SHOULD_return_false() { }

    I use underscore instead of camel case cause i feel it’s more easy to read and PHPUnit testdox can also substitute underscore with space just like it can spits out CamelCaseText into sentences. Some added bonus is, I can use CamelCaseText to describe something else like “WHEN_checking_validity_of_undefined_attribute_SHOULD_throw_RuntimeException” and testdox will write RuntimeException as is just like i need it ?.

    Previously, I prefix this formula with the actual tested method name like so “validate_WHEN_checking_on_undefined_attribute_SHOULD_throw_RuntimeException”. But i found that these isn’t practical as in early development stage I often found my self changing a method’s name for more descriptive name. And so, I have to change all the test method for it. It’s also makes me aware that what I’m testing is not the behavior of a method on the unit but the behavior of the unit as a whole. And by these, it makes me more alert when I violate SRP.

    I am not a native english speaker, so I apologize if this comment even makes you confused.

    LikeLike

    Reply