tipos - propiedades de las excepciones en c#

Cómo documentar las excepciones lanzadas en c#/. Net

Question

Actualmente estoy escribiendo un pequeño marco que será utilizado internamente por otros desarrolladores dentro de la compañía.

Quiero proporcionar buena información de Intellisense, pero no estoy seguro de cómo documentar las excepciones lanzadas.

En el siguiente ejemplo:

public void MyMethod1()
{
MyMethod2();
// also may throw InvalidOperationException
}
public void MyMethod2()
{
System.IO.File.Open(somepath...); // this may throw FileNotFoundException
// also may throw DivideByZeroException
}

Sé que el margen para documentar excepciones es:

/// <exception cref="SomeException">when things go wrong.</exception>

Lo que no entiendo es cómo documentar las excepciones lanzadas por el código llamado por MyMethod1() ?

• ¿Debo documentar excepciones lanzadas por MyMethod2()
• ¿Debo documentar excepciones lanzadas por File.Open() ?

¿Cuál sería la mejor manera de documentar posibles excepciones?

Answer 1

De hecho, como ya se ha respondido, la forma de documentar las excepciones es usar XML Comments.

Además de los complementos, también puede usar herramientas de análisis estático que se pueden integrar con TFS para asegurarse de tener las excepciones documentadas.

En los enlaces siguientes puede ver cómo se está documentando cómo crear una regla personalizada para StyleCop para validar las excepciones lanzadas por sus métodos.

http://www.josefcobonnin.com/post/2009/01/11/Xml-Documentation-Comments-Exceptions-I.aspx http://www.josefcobonnin.com/post/2009/01/15/Xml-Documentation-Comments-Exceptions-II.aspx

Saludos.

Answer 2

Debe documentar todas las excepciones que pueda generar su código, incluidas las de cualquier método al que pueda llamar.

Si la lista es un poco grande, es posible que desee crear su propio tipo de excepción. Capture todos los que pueda encontrar en su método, envuélvalos en su excepción y tírelos.

Otro lugar en el que puede querer hacerlo de esta manera es si su método está en la mira de su API. Al igual que una fachada simplifica múltiples interfaces en una sola interfaz, su API debería simplificar múltiples excepciones en una única excepción. Facilita el uso de tu código para las personas que llaman.

Para responder a algunas de las inquietudes de Andrew (de los comentarios), existen tres tipos de excepciones: las que no conoce, las que conoce y sobre las que no puede hacer nada, y las que conoce y sobre las que puede hacer algo al respecto.

Los que no sabes sobre ti quieren dejarlos ir. Es el principal de fallas rápidas: es mejor que la aplicación se bloquee antes que ingresar a un estado en el que podría terminar dañando sus datos. El bloqueo le informará sobre lo que sucedió y por qué, lo que puede ayudar a sacar esa excepción de la lista de "los que no conoce".

Los que conoce y sobre los que no puede hacer nada son excepciones como OutOfMemoryExceptions. En casos extremos, es posible que desee manejar excepciones como esta, pero a menos que tenga requisitos bastante notables, los tratará como la primera categoría: déjenlos ir. ¿Tienes que documentar estas excepciones? Te verías bastante tonto documentando OOM en cada método que crea un objeto nuevo.

Los que conoce y sobre los que puede hacer algo son los que debería documentar y envolver.

Puede encontrar algunas pautas más sobre el manejo de excepciones aquí.

Answer 3

Debe documentar todas las excepciones que su método podría generar.

Para ocultar los detalles de la implementación, trataría de manejar algunas excepciones de MyMethod2.

Podría considerar retrustarlos, si no puede manejar o resolver la excepción. Mayormente empaquetado / envuelto en una excepción más significativa para la persona que llama.

Answer 4

Debe usar la documentación xml estándar .

/// <exception cref="InvalidOperationException">Why it''s thrown.</exception>
/// <exception cref="FileNotFoundException">Why it''s thrown.</exception>
/// <exception cref="DivideByZeroException">Why it''s thrown.</exception>
public void MyMethod1()
{
MyMethod2();
// ... other stuff here
}
/// <exception cref="FileNotFoundException">Why it''s thrown.</exception>
/// <exception cref="DivideByZeroException">Why it''s thrown.</exception>
public void MyMethod2()
{
System.IO.File.Open(somepath...);
}
/// <exception cref="FileNotFoundException">Why it''s thrown.</exception>
public void MyMethod3()
{
try
{
MyMethod2();
}
catch (DivideByZeroException ex)
{
Trace.Warning("We tried to divide by zero, but we can continue.");
}
}

El valor de hacerlo de esta manera es que proporciona documentación de las excepciones conocidas que pueden ocurrir. Esta documentación está disponible en intellisense si está usando Visual Studio y puede recordarle a usted (u otros) más tarde las excepciones que puede esperar.

Desea especificar los tipos de excepciones específicos, ya que puede manejar un tipo de excepción, mientras que otros tipos son el resultado de un problema grave y no se pueden corregir.

Answer 5

Documente las excepciones esperadas en su método, en su ejemplo, le dejaría saber al usuario que ese método puede lanzar una excepción de archivo no encontrado.

Recuerde que es para informarle a la persona que llama sobre qué esperar para que puedan elegir cómo manejarlo.

Answer 6

Parte del contrato para su método debe ser verificar que las condiciones previas sean válidas, entonces:

public void MyMethod2()
{
System.IO.File.Open(somepath...); // this may throw FileNotFoundException
}

se convierte

/// <exception cref="FileNotFoundException">Thrown when somepath isn''t a real file.</exception>
public void MyMethod2()
{
FileInfo fi = new FileInfo( somepath );
if( !fi.Exists )
{
throw new FileNotFoundException("somepath doesn''t exists")
}
// Maybe go on to check you have permissions to read from it.
System.IO.File.Open(somepath...); // this may still throw FileNotFoundException though
}

Con este enfoque, es más fácil documentar todas las excepciones que OutOfMemoryException explícitamente sin tener que documentar también que se puede OutOfMemoryException una OutOfMemoryException , etc.

Answer 7

Por lo que entiendo, la intención de usar el elemento <exception> es usarlo cuando se decoran métodos, no excepciones:

/// <summary>Does something!</summary>
/// <exception cref="DidNothingException">Thrown if nothing is actually done.</exception>
public void DoSomething()
{
// There be logic here
}

Las excepciones que pueden lanzarse mediante otros métodos que se invocan deben capturarse, manejarse y documentarse en esos métodos. Se deben documentar las excepciones que eventualmente pueda lanzar .NET o las excepciones que su propio código haya lanzado explícitamente .

En cuanto a obtener algo más específico que eso, ¿tal vez pueda atrapar y lanzar sus propias excepciones personalizadas?

Answer 8

Puede facilitar el proceso de documentación utilizando varios complementos excelentes. Uno de ellos es GhostDoc , un complemento gratuito para Visual Studio que genera comentarios XML-doc. Además, si usa ReSharper , ReSharper un vistazo al excelente Agent Johnson Plugin para ReSharper, que agrega una opción para generar comentarios XML para excepciones arrojadas.

Actualización: parece que Agen Johnson no está disponible para R # 8, pago excepcional para ReSharper como alternativa ...

Paso 1: GhostDoc genera el comentario XML (Ctrl-Shift-D), mientras que el complemento Agent Johnson para ReSharper sugiere documentar también la excepción:

paso 1 http://i44.tinypic.com/bdwsk0.png

Paso 2: use la tecla de método abreviado de ReSharper (Alt-Intro) para agregar también la documentación de excepción:

paso 2 http://i41.tinypic.com/osdhm

Espero que ayude :)