cURL / Mailing Lists / curl-library / Single Mail

curl-library

Re: documenting unit tests for functions

From: Daniel Stenberg <daniel_at_haxx.se>
Date: Mon, 16 May 2011 00:02:37 +0200 (CEST)

On Sun, 15 May 2011, Amr Shahin wrote:

>> ... without reference to exact line number since that is doomed to change
>> over time, and unit-tests should preferably be focused on a single function
>> in each test anyway.

> I agree with no mentioning the line number, however we could use a more
> formal way by assigning a test-case-id to each function we test, it will
> look something like this:

[concept cut out]

Yes sure, it would work. I'm just not convinced that we need such an evolved
concept. It will require more work to add. It will require more work to
maintain and will more easily become wrong or incomplete. It seems to assume
that there's a single test case for a function, or you need to list multiple
test cases.

For me, the point of this data in the header is to provide two useful inputs
to the reader: A) that there is a unit test already done for the function and
B) where to find the test. I don't see any particular benefit in adding the
exact "test number" or position within the test file. If the developer wanting
to find a test case for a function but cannot find it with that information,
then adding more specific info won't help.

I think the info is good to have, but we should not provide more info than
necessary.

> this will make tests easy to find, especially if the developer only wants to
> take a look at the test to see what assumptions are made or how to call a
> certain API.

I think all functions should be documented in the function headers good enough
to explain how they should be used. If someone needs to read the tests to
figure out the API then we've not done a good enough job with that. (I know we
lack docs for a huge amount of functions atm...)

-- 
  / daniel.haxx.se
-------------------------------------------------------------------
List admin: http://cool.haxx.se/list/listinfo/curl-library
Etiquette:  http://curl.haxx.se/mail/etiquette.html
Received on 2011-05-16