Saya kira apa yang saya tanyakan adalah, apa cara terbaik untuk memastikan kode saya didokumentasikan dan diucapkan dengan benar untuk digunakan orang lain?
Sebagai sumber terbuka, komentar paling penting dari semua adalah komentar hak cipta dan perjanjian lisensi. Daripada komentar panjang yang panjang di awal setiap file, Anda mungkin ingin menggunakan yang pendek dan manis yang secara singkat menentukan hak cipta dan merujuk pembaca ke license.txt di direktori root.
Saya tahu Anda harus selalu mengomentari semuanya dan saya akan memasukkan fitur @params untuk setiap metode, tetapi apakah ada tips lain secara umum?
Beri komentar semuanya? Tidak. Komentari kode yang benar-benar membutuhkan komentar. Komentar hemat. Sebagai pengguna potensial dari sejumlah kode, manakah dari dua versi definisi kelas berikut yang akan Anda lihat?
Versi A:
class Foo {
private:
SomeType some_name; //!< State machine state
public:
...
/**
* Get the some_name data member.
* @return Value of the some_name data member.
*/
SomeType get_some_name () const { return some_name; }
...
};
Versi B:
/**
* A big long comment that describes the class. This class header comment is very
* important, but also is the most overlooked. The class is not self-documenting.
* Why is that class here? Your comments inside the class will say what individual parts
* do, but not what the class as a whole does. For a class, the whole is, or should be,
* greater than the parts. Do not forget to write this very important comment.
*/
class Foo {
private:
/**
* A big long comment that describes the variable. Just because the variable is
* private doesn't mean you don't have to describe it. You might have getters and
* setters for the variable, for example.
*/
SomeType some_name;
public:
...
// Getters and setters
...
// Getter for some_name. Note that there is no setter.
SomeType get_some_name () const { return some_name; }
...
};
Dalam versi A saya sudah mendokumentasikan semuanya - kecuali kelas itu sendiri. Kelas secara umum tidak mendokumentasikan diri sendiri. Komentar yang ada di versi A sama sekali tidak berguna, atau bahkan lebih buruk daripada tidak berguna. Itulah masalah utama dengan sikap "komentar segalanya". Komentar singkat tentang anggota data pribadi itu tidak mengomunikasikan apa pun, dan komentar doxygen pada pengambil memiliki nilai negatif. Sang pengambil get_some_name()tidak benar-benar membutuhkan komentar. Apa yang dilakukannya dan apa yang dikembalikan jelas dari kode. Bahwa tidak ada penyetel - Anda harus menyimpulkan bahwa itu tidak ada.
Dalam versi B saya telah mendokumentasikan apa yang perlu dikomentari. Sang pengambil tidak memiliki komentar doxygen, tetapi memiliki komentar yang menyebutkan bahwa tidak ada setter.
Buat komentar Anda diperhitungkan, dan berhati-hatilah bahwa komentar seringkali tidak dikelola untuk mencerminkan perubahan pada kode.