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.
API, (doxygen,phpdoc,etc) comments in test classes
Moderator: General Moderators
- Christopher
- Site Administrator
- Posts: 13596
- Joined: Wed Aug 25, 2004 7:54 pm
- Location: New York, NY, US
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.
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.
(#10850)
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:If you want to document your unit tests then follow your commenting standards.
.......
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.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.
.........
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());
}
}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?arborint wrote:........
I know people will howl because commenting has been beaten into most of us -- but there is a trend away from comments.
edit:
Spelling
- Maugrim_The_Reaper
- DevNet Master
- Posts: 2704
- Joined: Tue Nov 02, 2004 5:43 am
- Location: Ireland
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...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.
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.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.
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.
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?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.
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 rememberI must say this actually surprise me, but I assume you are not talking about away from all types of comments but the javaDoc type?