Cara mendokumentasikan pengecualian yang dilemparkan di c # /. Net

Saat ini saya sedang menulis kerangka kerja kecil yang akan digunakan secara internal oleh pengembang lain dalam perusahaan.

Saya ingin memberikan informasi Intellisense yang baik, tetapi saya tidak yakin bagaimana cara mendokumentasikan pengecualian yang dilemparkan.

Dalam contoh berikut:

public void MyMethod1()
{
    MyMethod2();

    // also may throw InvalidOperationException
}

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

    // also may throw DivideByZeroException
}

Saya tahu markup untuk mendokumentasikan pengecualian adalah:

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

Apa yang saya tidak mengerti adalah bagaimana mendokumentasikan pengecualian yang dilemparkan oleh kode yang dipanggil oleh MyMethod1() ?

• Haruskah saya mendokumentasikan pengecualian yang diajukan MyMethod2()
• Haruskah saya mendokumentasikan pengecualian yang diajukan File.Open()?

Apa cara terbaik untuk mendokumentasikan kemungkinan pengecualian?

Anda harus mendokumentasikan setiap pengecualian yang mungkin dilontarkan oleh kode Anda, termasuk yang ada dalam metode apa pun yang mungkin Anda panggil.

Jika daftar menjadi agak besar, Anda mungkin ingin membuat jenis pengecualian Anda sendiri. Tangkap semua yang mungkin Anda temui dalam metode Anda, bungkus dengan pengecualian Anda, dan buang itu.

Tempat lain yang mungkin ingin Anda lakukan dengan cara ini adalah jika metode Anda ada di depan API Anda. Seperti halnya fasad menyederhanakan banyak antarmuka menjadi satu antarmuka tunggal, API Anda harus menyederhanakan banyak pengecualian menjadi satu pengecualian. Membuat penggunaan kode Anda lebih mudah bagi penelepon.

Untuk menjawab beberapa kekhawatiran Andrew (dari komentar), ada tiga jenis pengecualian: Yang tidak Anda ketahui, yang Anda tahu dan tidak bisa lakukan, dan yang Anda tahu dan bisa Anda lakukan.

Yang Anda tidak tahu tentang Anda ingin melepaskannya. Ini adalah prinsip gagal cepat - lebih baik aplikasi Anda mogok daripada memasuki keadaan di mana Anda mungkin akhirnya merusak data Anda. Kecelakaan akan memberi tahu Anda tentang apa yang terjadi dan mengapa, yang dapat membantu memindahkan pengecualian itu dari daftar "yang tidak Anda ketahui".

Yang Anda ketahui dan tidak bisa lakukan adalah pengecualian seperti OutOfMemoryExceptions. Dalam kasus ekstrem, Anda mungkin ingin menangani pengecualian seperti ini, tetapi kecuali jika Anda memiliki beberapa persyaratan yang cukup luar biasa, Anda memperlakukannya seperti kategori pertama - biarkan mereka pergi. Apakah Anda harus mendokumentasikan pengecualian ini? Anda akan terlihat sangat bodoh mendokumentasikan OOM pada setiap metode yang baru saja menemukan objek.

Yang Anda tahu dan bisa lakukan sesuatu adalah yang harus Anda dokumentasikan dan bungkus.

Anda dapat menemukan beberapa panduan lebih lanjut tentang penanganan pengecualian di sini.

Anda harus menggunakan dokumentasi xml standar .

/// <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.");
    }
}

Nilai dalam melakukannya dengan cara ini adalah Anda memberikan dokumentasi pengecualian yang diketahui yang dapat terjadi. Dokumentasi ini tersedia di intellisense jika Anda menggunakan studio visual dan dapat mengingatkan Anda (atau orang lain) nanti tentang pengecualian yang dapat Anda harapkan.

Anda ingin menentukan jenis pengecualian tertentu, karena Anda mungkin dapat menangani satu jenis pengecualian, sementara jenis lainnya adalah hasil dari masalah serius dan tidak dapat diperbaiki.

Anda dapat membuat proses dokumentasi Anda lebih mudah dengan menggunakan beberapa peralatan tambahan yang hebat. Salah satunya adalah GhostDoc , add-in gratis untuk Visual Studio yang menghasilkan komentar XML-doc. Juga, jika Anda menggunakan ReSharper , lihat Plugin Agent Johnson yang luar biasa untuk ReSharper, yang menambahkan opsi untuk menghasilkan komentar XML untuk pengecualian yang dilemparkan.

Pembaruan: Tampaknya Agen Johnson tidak tersedia untuk R # 8, checkout Luar Biasa untuk ReSharper sebagai alternatif ...

Langkah 1: GhostDoc menghasilkan komentar XML (Ctrl-Shift-D), sementara plugin Agent Johnson untuk ReSharper menyarankan untuk mendokumentasikan pengecualian juga:

Langkah 2: Gunakan tombol pintas ReSharper (Alt-Enter) untuk menambahkan dokumentasi pengecualian juga:

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

Semoga itu bisa membantu :)

Dari apa yang saya pahami, niat menggunakan elemen <exception> adalah menggunakannya saat mendekorasi metode, bukan pengecualian:

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

Pengecualian yang dapat dilemparkan dengan metode lain yang disebut harus ditangkap, ditangani, dan didokumentasikan dalam metode tersebut. Pengecualian yang mungkin dilemparkan oleh .NET, atau pengecualian yang secara eksplisit dilemparkan oleh kode Anda sendiri harus didokumentasikan.

Sejauh mendapatkan lebih spesifik dari itu, mungkin Anda bisa menangkap dan melempar pengecualian Anda sendiri?

Bagian dari kontrak untuk metode Anda harus memastikan bahwa prasyarat tersebut valid, jadi:

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

menjadi

/// <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
}

Dengan pendekatan ini, lebih mudah untuk mendokumentasikan semua pengecualian yang Anda lemparkan secara eksplisit tanpa harus mendokumentasikan bahwa OutOfMemoryException mungkin ada yang dibuang, dll.

Anda harus mendokumentasikan semua pengecualian yang mungkin dapat dilemparkan dengan metode Anda.

Untuk menyembunyikan detail implementasi, saya akan mencoba menangani beberapa pengecualian dari MyMethod2 sendiri.

Anda dapat mempertimbangkan untuk mengembalikannya, jika Anda tidak dapat menangani atau memecahkan pengecualian. Sebagian besar dikemas / dibungkus dengan pengecualian yang lebih bermakna bagi penelepon.

Memang, seperti yang sudah dijawab, cara mendokumentasikan pengecualian menggunakan Komentar XML.

Selain plugin, Anda juga dapat menggunakan alat analisis statis yang dapat diintegrasikan dengan TFS untuk memastikan Anda memiliki pengecualian yang didokumentasikan.

Di tautan di bawah ini Anda dapat melihat cara membuat aturan khusus untuk StyleCop untuk memvalidasi pengecualian yang dilemparkan oleh metode Anda yang sedang didokumentasikan.

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

Salam.

Dokumentasikan pengecualian yang diharapkan dalam metode Anda, dalam contoh Anda, saya akan memberi tahu pengguna bahwa metode itu dapat membuang file tidak ditemukan pengecualian.

Ingatlah bahwa ini adalah untuk memberi tahu si penelepon tentang apa yang diharapkan sehingga mereka dapat memilih cara menghadapinya.