Konvensi penamaan kelas python google

Konvensi penamaan perpustakaan Python sedikit berantakan, jadi kita tidak akan pernah mendapatkan ini sepenuhnya konsisten

Perhatikan bahwa ini hanya mengacu pada pustaka standar Python. Jika mereka tidak bisa konsisten, maka hampir tidak ada banyak harapan untuk memiliki konvensi yang dipatuhi secara umum untuk semua kode Python, bukan?

Dari situ, dan diskusi di sini, saya akan menyimpulkan bahwa bukan dosa yang mengerikan jika terus menggunakan e. g. Konvensi penamaan Java atau C # (jelas dan mapan) untuk variabel dan fungsi saat beralih ke Python. Perlu diingat, tentu saja, bahwa yang terbaik adalah mematuhi gaya apa pun yang berlaku untuk basis kode / proyek / tim. Seperti yang ditunjukkan oleh Panduan Gaya Python, konsistensi internal paling penting

Untuk memberikan pengalaman pengembang yang konsisten di banyak API dan dalam jangka waktu yang lama, semua nama yang digunakan oleh API harus

• sederhana
• intuitif
• konsisten

Ini termasuk nama antarmuka, sumber daya, koleksi, metode, dan pesan

Karena banyak pengembang bukan penutur asli bahasa Inggris, salah satu tujuan dari konvensi penamaan ini adalah untuk memastikan bahwa sebagian besar pengembang dapat memahami API dengan mudah. Ini dilakukan dengan mendorong penggunaan kosakata yang sederhana, konsisten, dan kecil saat menyebutkan metode dan sumber daya

• Nama yang digunakan dalam API harus dalam bahasa Inggris Amerika yang benar. Misalnya, lisensi (bukan lisensi), warna (bukan warna)
• Bentuk pendek atau singkatan kata panjang yang diterima secara umum dapat digunakan untuk mempersingkat. Misalnya, API lebih disukai daripada Antarmuka Pemrograman Aplikasi
• Gunakan terminologi yang akrab dan intuitif jika memungkinkan. Misalnya, saat mendeskripsikan menghapus (dan menghancurkan) sumber daya, hapus lebih disukai daripada hapus
• Gunakan nama atau istilah yang sama untuk konsep yang sama, termasuk untuk konsep yang dibagikan di seluruh API
• Hindari nama yang berlebihan. Gunakan nama yang berbeda untuk konsep yang berbeda
• Hindari nama yang terlalu umum yang ambigu dalam konteks API dan ekosistem Google API yang lebih besar. Mereka dapat menyebabkan kesalahpahaman tentang konsep API. Sebaliknya, pilih nama spesifik yang menjelaskan konsep API secara akurat. Ini sangat penting untuk nama yang menentukan elemen API orde pertama, seperti sumber daya. Tidak ada daftar nama yang pasti untuk dihindari, karena setiap nama harus dievaluasi dalam konteks nama lain. Instance, info, dan service adalah contoh nama yang bermasalah di masa lalu. Nama yang dipilih harus menggambarkan konsep API dengan jelas (misalnya. contoh apa?) dan membedakannya dari konsep lain yang relevan (misalnya. apakah "peringatan" berarti aturan, sinyal, atau notifikasi?)
• Pertimbangkan dengan hati-hati penggunaan nama yang mungkin bertentangan dengan kata kunci dalam bahasa pemrograman umum. Nama tersebut dapat digunakan tetapi kemungkinan akan memicu pengawasan tambahan selama peninjauan API. Gunakan mereka dengan bijaksana dan hemat

Nama produk

Nama produk mengacu pada nama pemasaran produk API, seperti Google Calendar API. Nama produk harus digunakan secara konsisten oleh API, UI, dokumentasi, Persyaratan Layanan, laporan tagihan, kontrak komersial, dll. Google API harus menggunakan nama produk yang disetujui oleh tim produk dan pemasaran

Tabel di bawah menunjukkan contoh semua nama API terkait dan konsistensinya. Lihat lebih lanjut di bawah pada halaman ini untuk detail lebih lanjut tentang masing-masing nama dan konvensi mereka

// Google Watcher API
package google.watcher.v1;

// Google Watcher API
package google.watcher.v1;

// Google Watcher API
package google.watcher.v1;

// Google Watcher API
package google.watcher.v1;

// Google Watcher API
package google.watcher.v1;

// Google Watcher API
package google.watcher.v1;

Nama layanan

Nama layanan harus berupa nama DNS yang valid secara sintaksis (sesuai RFC 1035) yang dapat diselesaikan ke satu atau lebih alamat jaringan. Nama layanan Google API publik mengikuti polanya.

// Google Watcher API
package google.watcher.v1;

// Google Watcher API
package google.watcher.v1;

Jika API terdiri dari beberapa layanan, mereka harus diberi nama sedemikian rupa untuk membantu kemudahan penemuan. Salah satu cara untuk melakukannya adalah agar Nama Layanan memiliki awalan yang sama. Misalnya layanan

package google.calendar.v3;

// Specifies Java package name, using the standard prefix "com."
option java_package = "com.google.calendar.v3";

package google.calendar.v3;

// Specifies Java package name, using the standard prefix "com."
option java_package = "com.google.calendar.v3";

Nama paket

Nama paket dideklarasikan di API. file proto harus konsisten dengan Nama Produk dan Nama Layanan. Nama paket harus menggunakan nama komponen tunggal untuk menghindari campuran nama komponen tunggal dan jamak. Nama paket tidak boleh menggunakan garis bawah. Nama paket untuk API berversi harus diakhiri dengan versi. Sebagai contoh

// Google Calendar API
package google.calendar.v3;

API abstrak yang tidak terkait langsung dengan layanan, seperti Google Watcher API, harus menggunakan nama paket proto yang konsisten dengan nama Produk

// Google Watcher API
package google.watcher.v1;

Nama paket Java ditentukan dalam API. file proto harus cocok dengan nama paket proto dengan awalan nama paket Java standar (

package google.calendar.v3;

// Specifies Java package name, using the standard prefix "com."
option java_package = "com.google.calendar.v3";

package google.calendar.v3;

// Specifies Java package name, using the standard prefix "com."
option java_package = "com.google.calendar.v3";

package google.calendar.v3;

// Specifies Java package name, using the standard prefix "com."
option java_package = "com.google.calendar.v3";

package google.calendar.v3;

// Specifies Java package name, using the standard prefix "com."
option java_package = "com.google.calendar.v3";

ID koleksi

harus menggunakan bentuk jamak dan

package google.calendar.v3;

// Specifies Java package name, using the standard prefix "com."
option java_package = "com.google.calendar.v3";

package google.calendar.v3;

// Specifies Java package name, using the standard prefix "com."
option java_package = "com.google.calendar.v3";

package google.calendar.v3;

// Specifies Java package name, using the standard prefix "com."
option java_package = "com.google.calendar.v3";

package google.calendar.v3;

// Specifies Java package name, using the standard prefix "com."
option java_package = "com.google.calendar.v3";

Nama antarmuka

Untuk menghindari kebingungan seperti

// Library is the interface name.
service Library {
  rpc ListBooks(...) returns (...);
  rpc ...
}

// Library is the interface name.
service Library {
  rpc ListBooks(...) returns (...);
  rpc ...
}

// Library is the interface name.
service Library {
  rpc ListBooks(...) returns (...);
  rpc ...
}

Anda dapat menganggap nama layanan sebagai referensi untuk implementasi sebenarnya dari sekumpulan API, sedangkan nama antarmuka mengacu pada definisi abstrak API

Nama antarmuka harus menggunakan kata benda intuitif seperti Calendar atau Blob. Nama tidak boleh bertentangan dengan konsep mapan apa pun dalam bahasa pemrograman dan pustaka waktu prosesnya (misalnya, File)

Dalam kasus yang jarang terjadi ketika nama antarmuka bertentangan dengan nama lain dalam API, akhiran (misalnya

// Library is the interface name.
service Library {
  rpc ListBooks(...) returns (...);
  rpc ...
}

// Library is the interface name.
service Library {
  rpc ListBooks(...) returns (...);
  rpc ...
}

Nama metode

Sebuah layanan mungkin, dalam spesifikasi IDL-nya, menentukan satu atau lebih metode RPC yang sesuai dengan metode pada kumpulan dan sumber daya. Nama metode harus mengikuti konvensi penamaan

// Library is the interface name.
service Library {
  rpc ListBooks(...) returns (...);
  rpc ...
}

// Library is the interface name.
service Library {
  rpc ListBooks(...) returns (...);
  rpc ...
}

// Library is the interface name.
service Library {
  rpc ListBooks(...) returns (...);
  rpc ...
}

// Library is the interface name.
service Library {
  rpc ListBooks(...) returns (...);
  rpc ...
}

// Library is the interface name.
service Library {
  rpc ListBooks(...) returns (...);
  rpc ...
}

// Library is the interface name.
service Library {
  rpc ListBooks(...) returns (...);
  rpc ...
}

enum FooBar {
  // The first value represents the default and must be == 0.
  FOO_BAR_UNSPECIFIED = 0;
  FIRST_VALUE = 1;
  SECOND_VALUE = 2;
}

// Library is the interface name.
service Library {
  rpc ListBooks(...) returns (...);
  rpc ...
}

enum FooBar {
  // The first value represents the default and must be == 0.
  FOO_BAR_UNSPECIFIED = 0;
  FIRST_VALUE = 1;
  SECOND_VALUE = 2;
}

enum FooBar {
  // The first value represents the default and must be == 0.
  FOO_BAR_UNSPECIFIED = 0;
  FIRST_VALUE = 1;
  SECOND_VALUE = 2;
}

// Library is the interface name.
service Library {
  rpc ListBooks(...) returns (...);
  rpc ...
}

enum FooBar {
  // The first value represents the default and must be == 0.
  FOO_BAR_UNSPECIFIED = 0;
  FIRST_VALUE = 1;
  SECOND_VALUE = 2;
}

// Library is the interface name.
service Library {
  rpc ListBooks(...) returns (...);
  rpc ...
}

enum FooBar {
  // The first value represents the default and must be == 0.
  FOO_BAR_UNSPECIFIED = 0;
  FIRST_VALUE = 1;
  SECOND_VALUE = 2;
}

enum FooBar {
  // The first value represents the default and must be == 0.
  FOO_BAR_UNSPECIFIED = 0;
  FIRST_VALUE = 1;
  SECOND_VALUE = 2;
}

// Library is the interface name.
service Library {
  rpc ListBooks(...) returns (...);
  rpc ...
}

enum OldEnum {
  VALID = 0;
  OTHER_VALID = 1;
}
message OldEnumValue {
  OldEnum value = 1;
}

// Library is the interface name.
service Library {
  rpc ListBooks(...) returns (...);
  rpc ...
}

enum OldEnum {
  VALID = 0;
  OTHER_VALID = 1;
}
message OldEnumValue {
  OldEnum value = 1;
}

enum OldEnum {
  VALID = 0;
  OTHER_VALID = 1;
}
message OldEnumValue {
  OldEnum value = 1;
}

// Library is the interface name.
service Library {
  rpc ListBooks(...) returns (...);
  rpc ...
}

enum OldEnum {
  VALID = 0;
  OTHER_VALID = 1;
}
message OldEnumValue {
  OldEnum value = 1;
}

// Library is the interface name.
service Library {
  rpc ListBooks(...) returns (...);
  rpc ...
}

enum OldEnum {
  VALID = 0;
  OTHER_VALID = 1;
}
message OldEnumValue {
  OldEnum value = 1;
}

enum OldEnum {
  VALID = 0;
  OTHER_VALID = 1;
}
message OldEnumValue {
  OldEnum value = 1;
}

enum OldEnum {
  VALID = 0;
  OTHER_VALID = 1;
}
message OldEnumValue {
  OldEnum value = 1;
}

message FlightRecord {
  google.protobuf.Timestamp takeoff_time = 1;
  google.protobuf.Duration flight_duration = 2;
}

// Library is the interface name.
service Library {
  rpc ListBooks(...) returns (...);
  rpc ...
}

message FlightRecord {
  google.protobuf.Timestamp takeoff_time = 1;
  google.protobuf.Duration flight_duration = 2;
}

message FlightRecord {
  google.protobuf.Timestamp takeoff_time = 1;
  google.protobuf.Duration flight_duration = 2;
}

message FlightRecord {
  google.protobuf.Timestamp takeoff_time = 1;
  google.protobuf.Duration flight_duration = 2;
}

Bagian kata kerja dari nama metode harus menggunakan the , yaitu untuk perintah atau perintah daripada mood indikatif yang untuk pertanyaan

Untuk metode standar, bagian kata benda dari nama metode harus tunggal untuk semua metode kecuali

// Library is the interface name.
service Library {
  rpc ListBooks(...) returns (...);
  rpc ...
}

// Library is the interface name.
service Library {
  rpc ListBooks(...) returns (...);
  rpc ...
}

Ini mudah dibingungkan ketika kata kerjanya mengajukan pertanyaan tentang sub-sumber daya di API, yang sering diekspresikan dalam mood indikatif. Misalnya, memesan API untuk membuat buku jelas

enum FooBar {
  // The first value represents the default and must be == 0.
  FOO_BAR_UNSPECIFIED = 0;
  FIRST_VALUE = 1;
  SECOND_VALUE = 2;
}

message FlightRecord {
  google.protobuf.Timestamp takeoff_time = 1;
  google.protobuf.Duration flight_duration = 2;
}

xxx_{time|duration|delay|latency}_{seconds|millis|micros|nanos}

xxx_{time|duration|delay|latency}_{seconds|millis|micros|nanos}

xxx_{time|duration|delay|latency}_{seconds|millis|micros|nanos}

Nama metode tidak boleh menyertakan preposisi (mis. g. "Untuk", "Dengan", "Pada", "Kepada"). Umumnya, nama metode dengan preposisi menunjukkan bahwa metode baru sedang digunakan di mana bidang harus ditambahkan ke metode yang sudah ada, atau metode harus menggunakan kata kerja yang berbeda

Misalnya, jika pesan

enum FooBar {
  // The first value represents the default and must be == 0.
  FOO_BAR_UNSPECIFIED = 0;
  FIRST_VALUE = 1;
  SECOND_VALUE = 2;
}

xxx_{time|duration|delay|latency}_{seconds|millis|micros|nanos}

xxx_{time|duration|delay|latency}_{seconds|millis|micros|nanos}

Nama pesan

Nama pesan harus pendek dan ringkas. Hindari kata-kata yang tidak perlu atau berlebihan. Kata sifat seringkali dapat dihilangkan jika tidak ada pesan yang sesuai tanpa kata sifat. Misalnya,

xxx_{time|duration|delay|latency}_{seconds|millis|micros|nanos}

xxx_{time|duration|delay|latency}_{seconds|millis|micros|nanos}

Nama pesan tidak boleh menyertakan preposisi (mis. g. "Dengan", "Untuk"). Umumnya, nama pesan dengan preposisi lebih baik direpresentasikan dengan bidang opsional pada pesan

Pesan permintaan dan tanggapan

Pesan permintaan dan respons untuk metode RPC harus diberi nama setelah nama metode dengan akhiran

xxx_{time|duration|delay|latency}_{seconds|millis|micros|nanos}

xxx_{time|duration|delay|latency}_{seconds|millis|micros|nanos}

• pesan kosong (gunakan

  message FlightRecord {
    google.protobuf.Timestamp takeoff_time = 1;
    google.protobuf.Duration flight_duration = 2;
  }
  

  4),
• jenis sumber daya, atau
• sumber daya yang mewakili operasi

Ini biasanya berlaku untuk permintaan atau tanggapan yang digunakan dalam metode standar

enum FooBar {
  // The first value represents the default and must be == 0.
  FOO_BAR_UNSPECIFIED = 0;
  FIRST_VALUE = 1;
  SECOND_VALUE = 2;
}

enum FooBar {
  // The first value represents the default and must be == 0.
  FOO_BAR_UNSPECIFIED = 0;
  FIRST_VALUE = 1;
  SECOND_VALUE = 2;
}

enum OldEnum {
  VALID = 0;
  OTHER_VALID = 1;
}
message OldEnumValue {
  OldEnum value = 1;
}

message FlightRecord {
  google.protobuf.Timestamp takeoff_time = 1;
  google.protobuf.Duration flight_duration = 2;
}

Nama enum

Jenis Enum harus menggunakan nama UpperCamelCase

Nilai enum harus menggunakan CAPITALIZED_NAMES_WITH_UNDERSCORES. Setiap nilai enum harus diakhiri dengan titik koma, bukan koma. Nilai pertama harus diberi nama ENUM_TYPE_UNSPECIFIED karena dikembalikan saat nilai enum tidak ditentukan secara eksplisit

enum FooBar {
  // The first value represents the default and must be == 0.
  FOO_BAR_UNSPECIFIED = 0;
  FIRST_VALUE = 1;
  SECOND_VALUE = 2;
}

Pembungkus

Pesan yang mengenkapsulasi tipe enum proto2 dengan nilai

message Email {
  int64 send_time_millis = 1;
  int64 receive_time_millis = 2;
}

message Email {
  int64 send_time_millis = 1;
  int64 receive_time_millis = 2;
}

message Email {
  int64 send_time_millis = 1;
  int64 receive_time_millis = 2;
}

message Email {
  int64 send_time_millis = 1;
  int64 receive_time_millis = 2;
}

enum OldEnum {
  VALID = 0;
  OTHER_VALID = 1;
}
message OldEnumValue {
  OldEnum value = 1;
}

Nama bidang

Definisi bidang di. file proto harus menggunakan lower_case_underscore_separated_names. Nama-nama ini akan dipetakan ke konvensi penamaan asli dalam kode yang dihasilkan untuk setiap bahasa pemrograman

Nama bidang tidak boleh menyertakan preposisi (mis. g. "untuk", "selama", "di"), misalnya

• message Email {
    int64 send_time_millis = 1;
    int64 receive_time_millis = 2;
  }
  

  _9 seharusnya menjadi

  message StoreOpening {
    google.type.Date opening_date = 1;
    google.type.TimeOfDay opening_time = 2;
  }
  

  0

• message StoreOpening {
    google.type.Date opening_date = 1;
    google.type.TimeOfDay opening_time = 2;
  }
  

  1 seharusnya menjadi

  message StoreOpening {
    google.type.Date opening_date = 1;
    google.type.TimeOfDay opening_time = 2;
  }
  

  2

Nama bidang tidak boleh menggunakan kata sifat postpositive (pengubah ditempatkan setelah kata benda), misalnya

• message StoreOpening {
    google.type.Date opening_date = 1;
    google.type.TimeOfDay opening_time = 2;
  }
  

  3 seharusnya menjadi

  message StoreOpening {
    google.type.Date opening_date = 1;
    google.type.TimeOfDay opening_time = 2;
  }
  

  4

• message StoreOpening {
    google.type.Date opening_date = 1;
    google.type.TimeOfDay opening_time = 2;
  }
  

  5 seharusnya menjadi

  message StoreOpening {
    google.type.Date opening_date = 1;
    google.type.TimeOfDay opening_time = 2;
  }
  

  6

Nama bidang berulang

Kolom berulang di API harus menggunakan bentuk jamak yang tepat. Ini cocok dengan konvensi Google API yang ada, dan ekspektasi umum dari developer eksternal

Waktu dan Durasi

Untuk mewakili titik waktu yang tidak bergantung pada zona waktu atau kalender apa pun,

message StoreOpening {
  google.type.Date opening_date = 1;
  google.type.TimeOfDay opening_time = 2;
}

message StoreOpening {
  google.type.Date opening_date = 1;
  google.type.TimeOfDay opening_time = 2;
}

message StoreOpening {
  google.type.Date opening_date = 1;
  google.type.TimeOfDay opening_time = 2;
}

// Google Watcher API
package google.watcher.v1;

Jika waktu mengacu pada aktivitas, nama bidang harus berbentuk

// Google Watcher API
package google.watcher.v1;

// Google Watcher API
package google.watcher.v1;

// Google Watcher API
package google.watcher.v1;

// Google Watcher API
package google.watcher.v1;

// Google Watcher API
package google.watcher.v1;

Untuk mewakili rentang waktu antara dua titik waktu yang tidak bergantung pada kalender dan konsep seperti "hari" atau "bulan",

// Google Watcher API
package google.watcher.v1;

message FlightRecord {
  google.protobuf.Timestamp takeoff_time = 1;
  google.protobuf.Duration flight_duration = 2;
}

Jika Anda harus mewakili bidang terkait waktu menggunakan tipe bilangan bulat untuk alasan lama atau kompatibilitas, termasuk waktu jam dinding, durasi, penundaan, dan latensi, nama bidang harus memiliki formulir berikut

xxx_{time|duration|delay|latency}_{seconds|millis|micros|nanos}

message Email {
  int64 send_time_millis = 1;
  int64 receive_time_millis = 2;
}

Jika Anda harus merepresentasikan stempel waktu menggunakan tipe string untuk alasan warisan atau kompatibilitas, nama bidang tidak boleh menyertakan sufiks unit apa pun. Representasi string harus menggunakan format RFC 3339, mis. g. "2014-07-30T10. 43. 17Z"

Tanggal dan Waktu

Untuk tanggal yang tidak bergantung pada zona waktu dan waktu,

// Google Watcher API
package google.watcher.v1;

// Google Watcher API
package google.watcher.v1;

Untuk waktu yang tidak bergantung pada zona waktu dan tanggal,

// Google Watcher API
package google.watcher.v1;

// Google Watcher API
package google.watcher.v1;

message StoreOpening {
  google.type.Date opening_date = 1;
  google.type.TimeOfDay opening_time = 2;
}

Kuantitas

Kuantitas yang diwakili oleh tipe bilangan bulat harus menyertakan satuan pengukuran

// Google Watcher API
package google.watcher.v1;

Jika jumlahnya adalah sejumlah item, maka bidang harus memiliki akhiran

// Google Watcher API
package google.watcher.v1;

// Google Watcher API
package google.watcher.v1;

Bidang filter daftar

Jika API mendukung pemfilteran sumber daya yang dikembalikan oleh metode

// Library is the interface name.
service Library {
  rpc ListBooks(...) returns (...);
  rpc ...
}

// Google Watcher API
package google.watcher.v1;

// Google Watcher API
package google.watcher.v1;

Tanggapan daftar

Nama bidang dalam pesan respons metode

// Library is the interface name.
service Library {
  rpc ListBooks(...) returns (...);
  rpc ...
}

// Google Watcher API
package google.watcher.v1;

// Google Watcher API
package google.watcher.v1;

package google.calendar.v3;

// Specifies Java package name, using the standard prefix "com."
option java_package = "com.google.calendar.v3";

// Google Watcher API
package google.watcher.v1;

Kasus unta

Kecuali untuk nama kolom dan nilai enum, semua definisi di dalam file

// Google Watcher API
package google.watcher.v1;

Singkatan nama

Untuk singkatan nama terkenal di kalangan pengembang perangkat lunak, seperti

// Google Watcher API
package google.watcher.v1;

// Google Watcher API
package google.watcher.v1;

Apa gaya komentar untuk kelas di Python?

Panduan gaya apa yang digunakan Google?

Apa panduan gaya terbaik untuk Python?

Berapa lama garis dalam gaya Python Google?