Page 1 of 1

API, (doxygen,phpdoc,etc) comments in test classes

Posted: Wed May 24, 2006 6:18 pm
by fjoggen
Hi,
As a newcomer to the world of unit testing I was wondering if you consider it necessary to write documentation comments in your test classes. I am really unsure about this topic since the methods name in them self describes the test action. However it might be easier to grasp the complete picture in a API documentation generated by Doxygen (my favourite), phpDoc, phpdocumentor, etc.

One of the main reasons I am asking this is because I haven't been able to find any examples of unitesting which have been commented in the source. Another is that writing the test in them self increase the production time and writing heavy documentation on top of that might be a waste of coding time. Although one could argue that unit testing do decrease the overall production time, but that is another discussion....

So what is the grand masters of Unit testing recommendations and or preference?


PS
I have searched the forum, Google and yahoo, but either my search skills need some tuning or there simply isn't any discussion on the topic.

Posted: Wed May 24, 2006 6:25 pm
by Christopher
If you want to document your unit tests then follow your commenting standards.

I think it is telling that you cannot find examples of comments because the TDD/Agile crowd are subtly anti-comment. The attitude is that comments are just more text in that can be potentially incorrect. If the unit tests are the living documentation of the program, then comments and some programmer documentation is minimized. I know people will howl because commenting has been beaten into most of us -- but there is a trend away from comments.

Posted: Wed May 24, 2006 7:12 pm
by fjoggen
arborint wrote:If you want to document your unit tests then follow your commenting standards.
.......
To be honest since I am quite lazy, I would prefer to not comment my source files. However I realise that the laziest approach is to comment since it require the least effort in the long run.
arborint wrote:........
I think it is telling that you cannot find examples of comments because the TDD/Agile crowd are subtly anti-comment. The attitude is that comments are just more text in that can be potentially incorrect. If the unit tests are the living documentation of the program, then comments and some programmer documentation is minimised.
.........
I don't really see how unit test can act as the complete documentation to a program. That would mean, in a worst case scenario, that I would have to open two files to understand the source.

To be honest I think I will comment my unit test classes. However not as complete as my application source files, but just a small note on what exactly the purpose of the test is and other notes.

example:

Code: Select all

/**
 * Test that a requested path which doesn't point to a existing folder
 * in the application hierarchy throws a Configuration_Exception
 */
public function testInvalidRequestedPathThrowsConfiguration_Exception() {
    try {
        $formatedPath = Application_Structure::formatPath('configurati');
    } catch (Configuration_Exception $e) {
        $this->pass();
    } catch (Exception $e) {
        $this->fail('Unexpected Exception: ' . get_class($e) . ' width message: ' . $e->getMessage());
    }
}
The method name in itself is actually describing the same as the comment, but it is, at least for me (dyslexia), easier to scroll over a page and read the comment than a long and ugly methodname.
arborint wrote:........
I know people will howl because commenting has been beaten into most of us -- but there is a trend away from comments.
I must say this actually surprise me, but I assume you are not talking about away from all types of comments but the javaDoc type?

edit:
Spelling

Posted: Fri May 26, 2006 5:44 am
by Maugrim_The_Reaper
To be honest since I am quite lazy, I would prefer to not comment my source files. However I realise that the laziest approach is to comment since it require the least effort in the long run.
Commenting can be overused in many cases. Take the method in a class that runs to several dozen lines of code, does a few different steps, and each step needs to be commented for a later reviewer to understand what's happening. I'd argue commenting in this fashion is not all that useful. Might be worth more to just move each step out into a separate private method, with a nice descriptive name which summarises what it's for. Sure, you get extra methods, but the code is now more readable and the smaller methods might one day find a use elsewhere...
I don't really see how unit test can act as the complete documentation to a program. That would mean, in a worst case scenario, that I would have to open two files to understand the source.
I'm pretty new to Unit Testing myself. I tried it last Autumn for a while but I foundered about a lot. A few months ago after digesting my first experiences I spent more time learning the theory, and concentrated far less on the doing. I'm a theory-loving person, so once unit testing made sense in my world view, I picked it back up. At present I've applied it across one project, and am using it in another. My attitude change is like the one experienced after I figured out what OOP was all about.

One way to consider unit testing is what it does (as a test). It verifies that the expected behaviour of a class is continually maintained. If the behaviour changes while developing, your *frequent* test runs will pick it up instantly. The faster you become aware of a bug, the less time it takes to fix since the code you recently changed is fresh to mind. If you became aware of the same bug months down the line - you would need to hunt it down. Personally I hate bug hunting - it is the most wasteful use of my time imaginable.

Now since a unit test summarises the behaviour of a class - expected inputs/outputs/effects - it documents that class. Sure its not as pretty as phpDoc generated API documents, nor does it tell *how* class does something (that's in the code+comments) - it tells what the class is expected to do. And it does it quite well IMO. Of course there is such a thing as over-testing a class and the resulting unit tests can be so much gibberish at time. I'm still in that phase of experience I believe - I need more time to get a feel for what should and should not be tested.
To be honest I think I will comment my unit test classes. However not as complete as my application source files, but just a small note on what exactly the purpose of the test is and other notes.
I think one liner comments for a unit test actually add to its documentation role... You get more bang for the effort than you would commenting the actual class (though I still recommend commenting it in some fashion). I guess my summary - unittests+comments document expected behaviour, sourcecode+comments document how that behaviour is achieved. That make sense?
I must say this actually surprise me, but I assume you are not talking about away from all types of comments but the javaDoc type?
Depends on the level of documenting you aim for. I could not stand a class without phpDoc comments. Even if it has unit tests, relying on unit tests alone alienates users without a unit testing experience. Not all developers use unit testing (I'm a recent club applicant remember :)), so you need something for the masses to digest.