Should I document everyting in my method and test based on the documentation?

Question

Hi all, here is my question, as an example suppose i have a method to convert some types. something like this:

/// <summary>
/// Convierte el valor del objeto especificado a un valor equivalente de {T}.
/// </summary>
/// <typeparam name="T">El tipo del valor a regresar.</typeparam>
/// <param name="source">
/// Un objeto <see cref="string"/> con el valor a convertir.
/// </param>
/// <returns>
/// Un valor equivalente de <paramref name="source"/> de tipo {T} cuando la 
/// conversión se puede realizar, el valor por defecto de {T} en caso contrario.
/// </returns>
/// <exception cref="Exception">
/// Cuando <paramref name="source"/> no es un valor valido para {T}.
/// </exception>
/// <exception cref="FormatException">
/// Cuando <paramref name="source"/> no es un valor valido para {T}.
/// </exception>
/// <exception cref="NotSupportedException">
/// Cuando no se puede realizar la conversión.
/// </exception>
/// <exception cref="ArgumentNullException">
/// Cuando <paramref name="source"/> es <see langword="null"/>.
/// </exception>
/// <example>
public static T ToGeneric<T>(this string source) where T : IComparable {
    if(source == null) {
        throw new ArgumentNullException("source","Cant be null"); //just as an example
    }
    TypeConverter converter = TypeDescriptor.GetConverter(typeof(T));
    return ((T)converter.ConvertFrom(source));
}

As yo can see I documented every posible exception in the method, but only one (ArgumentNullException) is throwed by me.

I use my documentation as a base to create my TestCases, so in this case I would create 5 Test Cases, one for each exception and one for the correct case.

My questions if that the correct way to do it? If I follow my pattern sooner or later I will have a bunch of test for IO stuff that won't add any value. The only option I have thought is just document the exceptions that I create inside my method and also test only that, but some programmers at my work are not very good and they might get confused why the method is throwing a NotSupportedException if the parameter is not null (they speak Spanish by the way so reading the exception message is a bit harder for them)

Ho do you handle this kind of thing, document everything or just the things you actually do.

Thanks for your time.

Answer 1

It seems that all your exceptions are RuntimeExceptions. If you are really worried about properly documenting them (the purpose of which seems to be that the caller is expected to know about them and handle them), you should think about using checked exceptions. This way, the compiler creates (a minimum of) documentation automatically, and every programmer who calls the method has to think about the possible exceptions.

I use my documentation as a base to create my TestCases, so in this case I would create 5 Test Cases, one for each exception and one for the correct case.

That is a laudable approach. Many people just test the correct case (if at all). But again, the more relevant exceptions (the ones that a caller is supposed to handle somehow) should not be RuntimeExceptions.

As yo can see I documented every posible exception in the method, but only one (ArgumentNullException) is throwed by me.

Since this is unit testing, do not test the behaviour of dependencies (including their exceptions). Only test all code paths through your method, that means make it throw all of its own exceptions, and go throw all its catch blocks, but do not care about the unchecked exceptions. The "inherited" exceptions should be unit-tested within the test for the unit that produced them.