Komentar / Gaya Dokumentasi Dalam Kode

Ini mungkin pertanyaan bodoh, tapi sudah ada di benak saya untuk sementara waktu dan saya tidak dapat menemukan jawaban yang layak di tempat lain.

Saya memiliki guru yang mengatakan kita harus secara eksplisit mendaftar setiap parameter dengan deskripsi, meskipun hanya ada satu. Hal ini menyebabkan banyak pengulangan:

double MyFunction(const int MyParam);
// Function: MyFunction
// Summary: Does stuff with MyParam.
// Input: int MyParam - The number to do stuff with.
// Output: MyParam with stuff done to it.

Saat menulis dokumentasi dalam kode, seberapa detailnya Anda?

Sebagai permulaan, saya setuju bahwa baris "Function:" dalam contoh Anda sepenuhnya berlebihan. Ini juga merupakan pengalaman saya bahwa orang-orang yang mengajar di sekolah untuk menambahkan jenis komentar terus menambahkan jenis komentar itu dalam kode produksi mereka.

Komentar yang baik jangan ulangi apa yang ada dalam kode. Mereka menjawab pertanyaan "Mengapa?" bukannya "Apa?" atau bagaimana?" Mereka mencakup harapan tentang input, serta bagaimana kode akan berperilaku dalam kondisi tertentu. Mereka membahas mengapa algoritma X dipilih alih-alih algoritma Y. Singkatnya, persis hal-hal yang tidak akan jelas bagi orang lain ¹ dari membaca kode.

^{1: Seseorang yang terbiasa dengan bahasa kode ditulis. Jangan menulis komentar untuk mengajar, komentar untuk menambah informasi.}

Beberapa bahasa memiliki fitur pembuatan dokumen API seperti Ruby, Java, C # dan C ++ (melalui alat baris perintah). Ketika Anda memikirkannya dengan cara itu, itu membuat penulisan dokumen API jauh lebih penting. Lagi pula, itu menjawab pertanyaan "bagaimana saya lakukan ...?" Jadi saya tidak akan melakukan hal yang berulang seperti Function: MyFunctionketika nama fungsi jelas untuk dilihat semua orang. Alat pembuatan dokumen API cukup cerdas untuk melakukannya bagi saya. Namun, perincian berikut berguna, terutama pada metode / fungsi publik:

• Ringkasan (apa yang dilakukannya dan kapan relevan ringkasan tentang bagaimana menggunakannya)
• Daftar parameter dan apa yang diharapkan
• Apa nilai pengembalian (output) nantinya
• Segala pengecualian yang bisa dilontarkan secara eksplisit dan alasannya

Ini dapat menjadi alat referensi yang berguna ketika Anda mencoba untuk men-debug kode. Banyak IDE juga akan menggunakan dokumen API dalam kiat alat mereka saat Anda mengarahkan kursor ke nama fungsi.

Jika itu adalah bahasa tanpa fitur-fitur itu, komentar membantu, tetapi tidak sebanyak itu.

Jika ini adalah metode API publik maka ya Anda harus memberikan dokumentasi terperinci, terutama pada parameter dan perilaku yang diharapkan. Banyak orang merasa ini bisa santai untuk metode / fungsi pribadi, YMMV.

Secara keseluruhan saya lebih suka menulis kode bersih (metode / fungsi kecil yang melakukan satu hal dan satu hal dengan baik) dengan nama variabel yang masuk akal. Ini membuat sebagian besar kode Anda mendokumentasikan sendiri. Namun, saya tentu selalu mendokumentasikan setiap kasus tepi, penggunaan konkurensi dan algoritma yang kompleks.

Singkatnya anggaplah diri Anda sedikit lebih buruk untuk dipakai pada jam 3 pagi di 3 bulan dari sekarang. Anda akan berterima kasih pada diri sendiri untuk dokumen publik Anda yang luar biasa sebagai ganti mencari tahu apa arti parameter (bendera boolean) ...

Itu mirip dengan bagaimana kebanyakan kerangka kerja -Doc menguraikan dokumentasi dalam-kode (JavaDoc, PHPDoc, dll.).

Dari Jawa, dihasilkan secara otomatis oleh IDE:

/**
 * [Description]
 * @param str [Description]
 * @param isCondition [Description]
 * @return [Description]
 */
public int testFunction(String str, boolean isCondition) {
    ...
}

Ini adalah format yang sama yang digunakan untuk menghasilkan Dokumentasi untuk fitur bahasa bawaan - Contoh: http://download.oracle.com/javase/6/docs/api/java/lang/String.html

Format ini cukup membantu karena dengan jelas menunjukkan kepada pengguna pihak ketiga bagaimana berinteraksi dengan kode Anda. Jika fungsi Anda adalah metode pribadi yang hanya digunakan secara internal, maka itu bisa menjadi sedikit sia-sia - tetapi saya kira guru Anda mencoba membuat Anda menjadi praktik yang baik sampai Anda semua berpengalaman membuat perbedaan itu.

Satu-satunya bit saya sering menemukan agak berlebihan adalah deskripsi kembali - Biasanya hampir identik dengan deskripsi metode saya.

Ada dua tujuan untuk Komentar:

1. Mereka berfungsi untuk mengingatkan Anda dengan cepat apa yang kode Anda lakukan ketika Anda kembali ke sana beberapa bulan / tahun kemudian. Dengan cara ini Anda tidak perlu membaca ulang dan menganalisis kode Anda untuk menyegarkan ingatan Anda.
2. Mereka menyampaikan kepada orang lain yang mungkin membaca atau bekerja dengan kode Anda apa kode Anda lakukan.

Tentu saja ada banyak BANYAK cara berbeda untuk mendekati ini tetapi semakin teliti dan konsisten Anda semakin baik. Komentar yang efektif membutuhkan waktu untuk belajar seperti halnya pemrograman yang efektif. Ingatlah bahwa sulit untuk melihat titik komentar di sekolah karena tidak ada yang sedang Anda kerjakan yang cukup besar untuk benar-benar menjaminnya, tetapi mereka hanya mencoba memperkenalkannya kepada Anda. Dan biasanya cara mengajar Anda melakukannya adalah gaya profesor Anda, bukan standar apa pun. Kembangkan apa yang cocok untuk Anda. Dan ingat ... ada yang namanya komentar bodoh! :) Contoh:

a += 1; //adds 1 to the value in a

Betulkah? Terima kasih! LOL

Saya suka dokumentasi dari situs web PHP jadi saya menggunakan sesuatu yang mirip untuk komentar inline saya, dan menggunakan sintaks PHPDoc. Lihat contoh di bawah ini.

/*
* Finds all the locations where you have access to for this client and returns them in an array .
* @author Radu
* @version 1.0
* @param int $id ( The id of the client for which you're requesting access. )
* @param object $db ( A resource of type Mysql, representing a connection to mysql database, if not supplied the function will connect itself. )
* @return array ( Returns array with id's of locations that you are allowed to see, an empty array if you do not have acces to any locations or returns FALSE and triggers a Warning if any error occuread )
* @use array allowed_locations ( $id [, $db] )
*/
function allowed_locations($id, $db=NULL){ ... }

Dan seperti yang dikatakan @Larry Coleman, komentar inline harus memberi tahu mengapa Anda melakukan beberapa kode.

$funcResult = SomeFunction();
if(is_array($funcResult))
{    //Beacause SomeFunction() could return NULL, and count(NULL) = 1
    $c = count($funcResult);
} else {
    $c = 0;
}
if($c == 1)
{
 ... 
}else
{
 ...
}

Jika dalam pelayanan generasi Doc maka komentar lisan (meskipun menjengkelkan) mungkin merupakan hal yang baik. Meskipun Anda harus menjadikannya tujuan tim untuk tetap di atas komentar dan tetap mendapatkan informasi terbaru.

Kalau itu hanya gaya berkomentar saya akan memiliki masalah dengan itu. Komentar yang berlebihan dapat merusak kode sama seperti bantuan. Saya tidak dapat menghitung berapa kali saya menjumpai komentar dalam kode yang kedaluwarsa dan akibatnya menyesatkan. Saya biasanya mengabaikan komentar sekarang dan fokus membaca kode dan tes kode untuk memahami apa yang dilakukannya dan apa tujuannya.

Saya lebih suka kode yang jelas tidak berkomentar singkat . Berikan saya beberapa tes dengan pernyataan atau metode deskriptif dan saya senang dan mendapat informasi.