Geekly articles weekly

Panduan Gaya Google di C ++. Bagian 8

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



Saat menulis kode, kita semua menggunakan aturan desain kode. Terkadang aturan mereka sendiri ditemukan, dalam kasus lain, panduan gaya yang sudah jadi digunakan. Meskipun semua programmer C ++ membaca dalam bahasa Inggris lebih mudah daripada dalam bahasa asli mereka, itu lebih menyenangkan untuk memiliki manual dalam yang terakhir.
Artikel ini adalah terjemahan dari bagian panduan gaya Google di C ++ ke bahasa Rusia.
Artikel asli (garpu pada github), terjemahan yang diperbarui .

Penamaan


Aturan dasar untuk gaya pengkodean adalah penamaan. Penampilan nama segera (tanpa mencari iklan) memberi tahu kita apa itu: jenis, variabel, fungsi, konstan, makro, dll. Aturan penamaan bisa sewenang-wenang, tetapi konsistensi penting, dan aturan harus diikuti.

Prinsip Penamaan Umum


  • Gunakan nama yang bahkan orang-orang di tim lain akan mengerti.
  • Nama harus berbicara tentang tujuan atau penerapan objek.
  • Jangan menyimpan panjang nama, lebih baik memiliki nama yang lebih panjang dan lebih dimengerti (bahkan untuk pemula).
  • Lebih sedikit singkatan, terutama jika mereka tidak terbiasa di luar proyek.
  • Gunakan hanya singkatan yang diketahui (apakah Wikipedia tahu tentang mereka?).
  • Jangan mempersingkat kata-kata.

Secara umum, panjang nama harus sesuai dengan ukuran ruang lingkup. Sebagai contoh, n adalah nama yang cocok di dalam fungsi 5 baris, namun, ketika mendeskripsikan sebuah kelas, ini bisa sedikit pendek.

class MyClass { public: int CountFooErrors(const std::vector<Foo>& foos) { int n = 0; //       for (const auto& foo : foos) { ... ++n; } return n; } void DoSomethingImportant() { std::string fqdn = ...; //      } private: const int kMaxAllowedConnections = ...; //     }; 

 class MyClass { public: int CountFooErrors(const std::vector<Foo>& foos) { int total_number_of_foo_errors = 0; //       for (int foo_index = 0; foo_index < foos.size(); ++foo_index) { //   `i` ... ++total_number_of_foo_errors; } return total_number_of_foo_errors; } void DoSomethingImportant() { int cstmr_id = ...; //   ( ) } private: const int kNum = ...; //       };

Perhatikan bahwa nama-nama umum juga valid: i untuk iterator atau penghitung, T untuk parameter templat.

Di masa depan, ketika menggambarkan aturan "kata" / "kata" adalah semua yang ditulis dalam bahasa Inggris tanpa spasi, termasuk singkatan. Singkatnya, huruf pertama dapat ditulis dengan huruf besar (tergantung gaya: " camel case " atau "case Pascal"), huruf yang tersisa adalah huruf kecil. Misalnya, lebih disukai StartRpc () , lebih disukai StartRPC () .

Parameter template juga mengikuti aturan kategorinya: Ketikkan nama, nama variabel, dll ...

Nama file


Nama file harus ditulis hanya dalam huruf kecil, Anda dapat menggunakan garis bawah ( _ ) atau tanda hubung ( - ) untuk memisahkannya. Gunakan pemisah yang digunakan dalam proyek. Jika tidak ada pendekatan tunggal, gunakan "_".

Contoh nama yang cocok:

  • my_useful_class.cc
  • my-useful-class.cc
  • myusefulclass.cc
  • myusefulclass_test.cc // _unittest dan _regtest tidak digunakan lagi.

File C ++ harus diakhiri dengan .cc , tajuk harus dalam
.h . File yang dimasukkan sebagai teks harus diakhiri dengan .inc (lihat juga bagian Independent Header ).

Jangan menggunakan nama yang sudah ada di / usr / include , seperti db.h.

Coba berikan file nama tertentu. Misalnya, http_server_logs.h lebih baik daripada logs.h. Ketika file digunakan berpasangan, yang terbaik adalah memberi mereka nama yang sama. Misalnya, foo_bar.h dan foo_bar.cc (dan berisi kelas FooBar ).

Ketikkan nama


Ketik nama dimulai dengan huruf kapital, setiap kata baru juga dimulai dengan huruf kapital. Garis bawah tidak digunakan: MyExcitingClass , MyExcitingEnum .

Nama semua jenis - kelas, struktur, alias, enumerasi, parameter templat - diberi nama dengan gaya yang sama. Ketik nama dimulai dengan huruf kapital, setiap kata baru juga dimulai dengan huruf kapital. Garis bawah tidak digunakan. Sebagai contoh:

 // classes and structs class UrlTable { ... class UrlTableTester { ... struct UrlTableProperties { ... // typedefs typedef hash_map<UrlTableProperties *, std::string> PropertiesMap; // using aliases using PropertiesMap = hash_map<UrlTableProperties *, std::string>; // enums enum UrlTableErrors { ...

Nama variabel


Nama-nama variabel (termasuk parameter fungsi) dan anggota data ditulis dalam huruf kecil dengan garis bawah di antara kata-kata. Anggota kelas-kelas ini (bukan struktur) dilengkapi dengan garis bawah pada akhir nama. Misalnya: a_local_variable , a_struct_data_member , a_class_data_member_ .

Nama Variabel Umum


Sebagai contoh:

 std::string table_name; // OK -     

 std::string tableName; //  -

Anggota data kelas


Anggota kelas-kelas ini, statis dan non-statis, disebut sebagai variabel biasa dengan penambahan garis bawah di akhir.

 class TableInfo { ... private: std::string table_name_; // OK -    static Pool<TableInfo>* pool_; // OK. };

Struktur anggota data


Anggota data struktur, statis dan non-statis, disebut sebagai variabel reguler. Tidak ada garis bawah yang ditambahkan pada mereka di akhir.

 struct UrlTableProperties { std::string name; int num_entries; static Pool<UrlTableProperties>* pool; };

Lihat juga Structures vs Classes , yang menjelaskan kapan harus menggunakan struktur, kapan kelas.

Nama konstanta


Objek dideklarasikan sebagai constexpr atau const, sehingga nilainya tidak berubah selama eksekusi. Nama-nama konstanta dimulai dengan simbol "k", kemudian muncul nama dalam gaya campuran (huruf besar dan kecil). Garis bawah dapat digunakan dalam kasus yang jarang terjadi ketika huruf besar tidak dapat digunakan untuk pemisahan. Sebagai contoh:

 const int kDaysInAWeek = 7; const int kAndroid8_0_0 = 24; // Android 8.0.0

Semua objek konstan serupa dengan jenis penyimpanan statis (mis. Statis atau global, untuk detail lebih lanjut di sini: Durasi Penyimpanan ) juga dinamai. Konvensi ini bersifat opsional untuk variabel dalam jenis penyimpanan lain (misalnya, objek konstan otomatis).

Nama fungsi


Fungsi umum dinamai dalam gaya campuran (huruf besar dan kecil); fungsi akses variabel (accessor dan mutator) harus memiliki gaya yang mirip dengan variabel target.

Biasanya, nama fungsi dimulai dengan huruf kapital dan setiap kata dalam nama ditulis dengan huruf kapital.

 void AddTableEntry(); void DeleteUrl(); void OpenFileOrDie();

(Aturan serupa berlaku untuk konstanta di area kelas atau namespace yang merupakan bagian dari API dan harus terlihat seperti fungsi (dan fakta bahwa mereka bukan fungsi tidak kritis))

Accessor dan mutators (get and set functions) dapat dinamai seperti variabel yang sesuai. Mereka sering berhubungan dengan variabel anggota nyata, tetapi ini tidak perlu. Misalnya, jumlah int () dan membatalkan set_count (jumlah int) .

Namespace Namespace


Namespace disebut huruf kecil. Namespace tingkat atas didasarkan pada nama proyek. Hindari tabrakan nama Anda dan ruang nama terkenal lainnya.

Namespace tingkat atas biasanya adalah nama proyek atau tim (yang membuat kode). Kode tersebut harus berada di direktori (atau subdirektori) dengan nama yang sesuai dengan namespace.

Jangan lupa aturan untuk tidak menggunakan singkatan - ini juga berlaku untuk ruang nama. Kode di dalamnya tidak membutuhkan referensi namespace, jadi singkatannya berlebihan.

Hindari menggunakan nama yang dikenal untuk ruang nama bersarang. Tabrakan antara nama dapat menyebabkan kejutan selama pertemuan. Secara khusus, jangan membuat ruang nama bersarang bernama std . Pengidentifikasi proyek yang unik ( websearch :: index , websearch :: index_util ) direkomendasikan daripada tidak aman terhadap tabrakan websearch :: util .

Untuk ruang nama internal / internal , tabrakan dapat terjadi ketika kode lain ditambahkan (pembantu internal cenderung mengulang pada tim yang berbeda). Dalam hal ini, menggunakan nama file untuk memberi nama namespace sangat membantu. ( websearch :: index :: frobber_internal untuk digunakan di frobber.h )

Nama Enumerasi


Pencacahan (keduanya dengan batasan ruang lingkup dan tanpa penutup) harus disebut sebagai konstanta atau makro . Yaitu: kEnumName atau ENUM_NAME .

Lebih disukai untuk menyebutkan nilai-nilai individual dalam enumerator sebagai konstanta. Namun, diizinkan untuk menyebutnya sebagai makro. Nama enumerasi UrlTableErrors (dan AlternateUrlTableErrors ) itu sendiri adalah sebuah tipe. Akibatnya, gaya campuran digunakan.

 enum UrlTableErrors { kOk = 0, kErrorOutOfMemory, kErrorMalformedInput, }; enum AlternateUrlTableErrors { OK = 0, OUT_OF_MEMORY = 1, MALFORMED_INPUT = 2, };

Sampai Januari 2009, gaya penamaan nilai-nilai enumerasi seperti makro. Ini menciptakan masalah dengan nama makro duplikat dan nilai enumerasi. Menerapkan gaya konstan memecahkan masalah dan lebih baik menggunakan gaya konstan dalam kode baru. Namun, tidak perlu menulis ulang kode lama (selama tidak ada masalah duplikasi).

Nama makro


Apakah Anda tidak akan mendefinisikan makro ? Untuk jaga-jaga (jika Anda akan), mereka akan terlihat seperti ini:
MY_MACRO_THAT_SCARES_SMALL_CHILDREN_AND_ADULTS_ALIKE .

Baca cara mendefinisikan makro ; Biasanya, makro tidak boleh digunakan. Namun, jika Anda benar-benar membutuhkannya, beri nama dengan huruf kapital dengan garis bawah.

 #define ROUND(x) ... #define PI_ROUNDED 3.0

Memberi Pengecualian


Jika Anda perlu memberi nama sesuatu yang memiliki analog dengan kode C atau C ++ yang ada, maka ikuti gaya yang digunakan dalam kode tersebut.

bigopen ()
nama fungsi berasal dari open ()

kamu tidak
definisi mirip dengan tipe standar

bigpos
struct atau kelas berasal dari pos

sparse_hash_map
Entitas seperti STL; ikuti gaya stl

LONGLONG_MAX
konstan seperti INT_MAX

Catatan: Tautan dapat mengarah ke bagian-bagian manual yang belum diterjemahkan.

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

More articles:


All Articles