Geekly articles weekly

Panduan Gaya Google di C ++. Bagian 9

Bagian 1. Pendahuluan
...
Bagian 8. Penamaan
Bagian 9. Komentar
...


Artikel ini adalah terjemahan dari bagian panduan gaya Google di C ++ ke bahasa Rusia.
Artikel asli (garpu pada github), terjemahan yang diperbarui .

Komentar


Diperlukan komentar untuk kode tersebut (jika Anda berencana untuk membacanya). Aturan berikut menjelaskan apa yang harus Anda komentari dan bagaimana. Tapi ingat: sementara komentar sangat penting, kode yang sempurna adalah dokumentasi sendiri. Penggunaan nama "berbicara" untuk jenis dan variabel jauh lebih baik daripada nama yang tidak jelas, yang kemudian harus ditulis dalam komentar.

Komentari kode dengan mempertimbangkan pembacanya berikut: programmer yang perlu memahami kode Anda. Ingatlah bahwa Anda dapat menjadi pembaca berikutnya!

Gaya Komentar


Gunakan // atau / * * / sampai keseragaman dilanggar.

Anda dapat menggunakan // atau / ** / , namun // lebih disukai. Namun, selalu selaraskan gaya komentar Anda dengan kode yang ada.

Komentar di header file


Masukkan header lisensi di bagian atas setiap file.

Komentar dalam file harus menjelaskan isinya. Jika file menyatakan, menjelaskan, atau menguji satu abstraksi (yang sudah ada komentar), deskripsi tambahan di header file tidak diperlukan. Jika tidak, masukkan deskripsi konten di bagian atas file.

Informasi hukum dan daftar penulis


Setiap file harus mengandung informasi lisensi. Format uraian tergantung pada lisensi yang digunakan dalam proyek. Setiap lisensi (Apache 2.0, BSD, LGPL, GPL, dll.) Dapat memiliki persyaratan desain sendiri.

Jika Anda membuat perubahan signifikan pada file, pertimbangkan menghapus daftar penulis sebelumnya. File yang diperbarui mungkin tidak lagi berisi penyebutan hak cipta dan daftar penulis.

Isi file


Jika .h mendeklarasikan beberapa abstraksi, komentar pada header file pada umumnya harus menggambarkan isi file dan bagaimana abstraksi tersebut saling berhubungan satu sama lain. Satu, dua kalimat dalam komentar biasanya cukup. Informasi lebih rinci ditandatangani di tempat lain (bukan di header file).

Jangan menggandakan komentar dalam file .h dan .cc - komentar menjadi berbeda dari waktu ke waktu.

Komentar kelas


Setiap deklarasi kelas (kecuali yang sangat jelas) harus disertai dengan komentar, untuk apa kelas dan bagaimana menggunakannya.

//   GargantuanTable. // : // GargantuanTableIterator* iter = table->NewIterator(); // for (iter->Seek("foo"); !iter->done(); iter->Next()) { // process(iter->key(), iter->value()); // } // delete iter; class GargantuanTableIterator { ... };

Komentar pada kelas harus cukup untuk memahami: bagaimana dan kapan menggunakan kelas, persyaratan tambahan untuk penggunaan kelas yang benar. Jelaskan, jika perlu, batasan (asumsi) pada sinkronisasi di kelas. Jika turunan dari kelas dapat digunakan dari utas yang berbeda, pastikan untuk menuliskan aturan multi-utas.

Anda juga dapat memberikan contoh kode pendek dalam komentar kelas untuk menunjukkan betapa mudahnya menggunakan kelas.

Biasanya, kelas dideklarasikan / didefinisikan dalam file yang berbeda ( .h dan .cc ). Komentar yang menggambarkan penggunaan kelas harus di sebelah definisi antarmuka. Komentar tentang kerumitan implementasi harus dekat dengan kode metode itu sendiri.

Komentar Fungsi


Komentar pada deklarasi fungsi harus menggambarkan penggunaan fungsi (kecuali dalam kasus yang paling jelas). Komentar pada definisi fungsi menjelaskan implementasi.

Deklarasi Fungsi


Deklarasi masing-masing fungsi harus memiliki komentar (tepat sebelum deklarasi), apa fungsinya dan bagaimana menggunakannya. Sebuah komentar dapat dihilangkan hanya jika fungsinya sederhana dan penggunaannya jelas (misalnya, fungsi mengurangkan nilai variabel). Cobalah untuk memulai komentar dalam suasana indikatif ("Buka file"). Menggunakan mood imperatif ("Buka File") tidak dianjurkan. Sebuah komentar menggambarkan esensi suatu fungsi, bukan bagaimana fungsinya.

Dalam komentar pada deklarasi fungsi, perhatikan hal berikut:

  • Apa yang diumpankan ke input fungsi, yang dikembalikan sebagai hasilnya.
  • Untuk fungsi anggota kelas: apakah instance menyimpan argumen referensi,
    Apakah saya perlu membebaskan memori.
  • Apakah fungsi mengalokasikan memori yang harus dihapus oleh kode panggilan.
  • Bisakah ada argumen nullptr.
  • Kompleksitas fungsi (algoritmik).
  • Apakah panggilan dari utas berbeda diizinkan pada saat yang sama? Bagaimana dengan sinkronisasi?

Contoh:

 //    .    //   .    //    GargantuanTable  . // //      . // //    : // Iterator* iter = table->NewIterator(); // iter->Seek(""); // return iter; //         , //    NewIterator()     . Iterator* GetIterator() const;

Namun, jangan mengunyah hal-hal yang sudah jelas.

Saat mendokumentasikan fungsi kelebihan beban, buat perubahan keras kepala utama dibandingkan dengan fungsi asli. Dan jika tidak ada perubahan (yang sering terjadi), maka komentar tambahan tidak diperlukan sama sekali.

Ketika mengomentari konstruktor dan destruktor, perlu diingat bahwa pembaca kode tahu tujuan mereka. Oleh karena itu, komentar jenis "menghancurkan objek ini" adalah bodoh. Anda dapat menggambarkan apa yang dilakukan konstruktor dengan argumen (misalnya, mengubah kepemilikan pointer) atau operasi pembersihan seperti apa yang dilakukan destruktor. Jika semuanya jelas, jangan berkomentar apa pun. Secara umum, destruktor biasanya tidak memiliki komentar (ketika dideklarasikan).

Definisi Fungsi


Jika ada trik dalam implementasi fungsi, Anda dapat menambahkan komentar penjelasan ke definisi. Di dalamnya Anda dapat mendeskripsikan trik-trik dengan kode, memberikan gambaran umum dari semua tahapan perhitungan, menjelaskan pilihan implementasi ini atau itu (terutama jika ada alternatif yang lebih baik). Anda dapat menjelaskan prinsip-prinsip sinkronisasi kode (di sini kami memblokir, tetapi di sini kami membungkus ikan).

Perhatikan bahwa Anda tidak boleh mengulangi komentar pada deklarasi fungsi (dari file .h atau sejenisnya). Dapat dijelaskan secara singkat apa fungsi tersebut, tetapi hal utama yang harus diperhatikan adalah bagaimana melakukannya.

Komentar pada Variabel


Dalam cara yang baik, nama variabel harus segera mengatakan apa itu dan mengapa.Namun, dalam beberapa kasus, komentar tambahan diperlukan.

Anggota data kelas


Tujuan setiap anggota kelas harus jelas. Jika ada kehalusan yang tidak jelas (makna khusus, hubungan dengan anggota lain, batasan seumur hidup) - semua ini perlu dikomentari. Namun, jika jenis dan namanya cukup - Anda tidak perlu menambahkan komentar.

Di sisi lain, deskripsi nilai khusus (dan tidak jelas) (nullptr atau -1) akan berguna. Sebagai contoh:

 private: //       // -1 - ,         int num_total_entries_;

Variabel global


Semua variabel global harus dikomentari tentang tujuannya dan (jika tidak jelas) mengapa mereka harus global. Misalnya:

 //   ,     const int kNumTestCases = 6;

Komentar tentang implementasi


Mengomentari implementasi fungsi atau algoritma dalam kasus potongan kode yang tidak jelas, menarik, dan penting.

Komentar deskriptif


Blok kode yang kompleks atau non-standar harus diawali dengan komentar. Sebagai contoh:

 //    2.  x    for (int i = 0; i < result->size(); ++i) { x = (x << 8) + (*result)[i]; (*result)[i] = x >> 1; x &= 1; }

Komentar baris


Dianjurkan untuk melengkapi baris kode dengan makna yang tidak jelas dengan komentar (biasanya terletak di akhir baris). Komentar ini harus dipisahkan dari kode dengan 2 spasi. Sebagai contoh:

 //   ,    mmap_budget = max<int64>(0, mmap_budget - index_->length()); if (mmap_budget >= data_size_ && !MmapData(mmap_chunk_bytes, mlock)) return; //

Perhatikan bahwa ada 2 komentar pada blok kode: satu menjelaskan apa yang dilakukan kode, yang lain mengingat bahwa kesalahan sudah ada dalam log jika ada pengembalian dari fungsi.

Komentar pada Argumen Fungsi


Saat menetapkan argumen ke suatu fungsi tidak jelas, pertimbangkan opsi berikut:

  • Jika argumennya adalah nilai tetap (konstanta literal) dan nilai itu
    digunakan dalam blok kode yang berbeda (dan dipahami bahwa nilai ini adalah hal yang sama)
    Anda harus membuat konstanta dan menggunakannya secara eksplisit.
  • Mungkin Anda harus mengganti argumen tipe bool dengan
    enum enum . Ini akan membuat argumen menentukan sendiri.
  • Untuk fungsi yang menggunakan beberapa opsi konfigurasi dalam argumen, Anda bisa
    buat kelas terpisah (atau struktur) yang menggabungkan semua opsi. Dan lulus berfungsi
    sebuah instance dari kelas ini.
    Pendekatan ini memiliki beberapa keunggulan: opsi ditunjukkan dengan nama, yang menjelaskan
    tujuan mereka. Jumlah argumen dalam fungsi berkurang - kode lebih mudah ditulis dan dibaca.
    Dan jika Anda perlu menambahkan lebih banyak opsi, Anda tidak perlu mengubah panggilan fungsi itu sendiri.
  • Alih-alih ekspresi kompleks dalam argumen, gunakan variabel perantara yang Anda tetapkan ekspresi.
  • Sebagai upaya terakhir, tulis komentar di tempat pemanggilan untuk memperjelas tujuan argumen.

Perhatikan contoh-contoh berikut:

 //    ? const DecimalNumber product = CalculateProduct(values, 7, false, nullptr);

Mari kita coba menyisir kode:

 ProductOptions options; options.set_precision_decimals(7); options.set_use_cache(ProductOptions::kDontUseCache); const DecimalNumber product = CalculateProduct(values, options, /*completion_callback=*/nullptr);

Apa yang tidak boleh dilakukan


Jangan jelaskan yang jelas. Secara khusus, tidak perlu menjelaskan hal-hal yang jelas bagi orang yang tahu C ++. Sebagai gantinya, Anda dapat menjelaskan mengapa kode ini melakukannya (atau bahkan membuat kode itu menggambarkan diri sendiri).

Bandingkan:

 //    . <-- :  ! auto iter = std::find(v.begin(), v.end(), element); if (iter != v.end()) { Process(element); }

Dengan ini:

 //  (Process) "element"     auto iter = std::find(v.begin(), v.end(), element); if (iter != v.end()) { Process(element); }

Kode yang menggambarkan sendiri tidak memerlukan komentar sama sekali.
Komentar pada kode di atas mungkin secara umum jelas (dan tidak perlu):

 if (!IsAlreadyProcessed(element)) { Process(element); }

Tanda Baca, Ejaan, dan Tata Bahasa


Perhatikan tanda baca, ejaan, dan tata bahasa: jauh lebih mudah untuk membaca komentar yang ditulis dengan benar.

Komentar harus ditulis sebagai cerita: dengan susunan huruf kapital dan tanda baca yang benar. Dalam kebanyakan kasus, kalimat lengkap lebih mudah dipahami daripada fragmen frasa. Komentar singkat, seperti baris demi baris, mungkin kurang formal, tetapi harus tetap mengikuti gaya umum.

Meskipun penekan kode yang terlalu banyak menggunakan koma alih-alih titik koma bisa sedikit mengganggu, penting untuk menjaga tingkat keterbacaan dan pemahaman yang tinggi. Tanda baca, ejaan, dan tata bahasa yang tepat berkontribusi besar dalam hal ini.

Komentar TODO


Gunakan komentar TODO untuk kode sementara atau solusi yang cukup baik (menengah, tidak sempurna).

Komentar harus mencakup baris TODO (semua huruf besar), diikuti dengan nama, alamat e-mail, ID cacat atau informasi lain untuk mengidentifikasi pengembang dan sifat dari masalah yang ditulis TODO . Tujuan deskripsi ini adalah untuk dapat menemukan rincian lebih lanjut nanti. TODO dengan deskripsi tidak berarti bahwa pemrogram yang ditentukan akan memperbaiki masalah. Karena itu, ketika Anda membuat TODO , nama yang biasa adalah nama Anda.

 // TODO(kl@gmail.com):  "*"  . // TODO(Zeke)   . // TODO(bug 12345):   " ".

Jika TODO Anda terlihat seperti "Mari kita lakukan secara berbeda di masa mendatang", maka sebutkan tanggal tertentu ("Benar di bulan November 2005") atau acara ("Hapus kode itu ketika semua klien akan memproses permintaan XML").

Catatan:
- Tautan dapat mengarah ke bagian-bagian manual yang belum diterjemahkan.
- diskusi tentang masalah umum paling baik dilakukan di Bagian 1. Pendahuluan

Source: https://habr.com/ru/post/id480424/

More articles:


All Articles