Panduan Google untuk Memformat Kode Java

1. Perkenalan

Dokumen ini menjelaskan standar pengkodean dalam bahasa pemrograman Java di Google. Kode sumber Java dianggap sesuai dengan standar ini jika, dan hanya jika, memenuhi semua aturan yang dijelaskan dalam dokumen ini.



Topik yang dibahas dalam tutorial ini tidak hanya tentang sisi estetika pemformatan kode, tetapi juga jenis konvensi atau standar pengkodean lainnya. Namun, dokumen ini berkonsentrasi terutama pada mendefinisikan aturan ketat yang kami ikuti di mana pun, dan tidak memberikan rekomendasi yang dapat diterapkan secara tidak benar (baik oleh manusia maupun oleh peralatan mesin).

1.1 Istilah

Dalam panduan ini, istilah-istilah berikut didefinisikan:

1. Istilah kelas digunakan untuk mengartikan kelas "biasa", enumerasi, antarmuka atau jenis anotasi (@interface)
2. Anggota kelas istilah digunakan untuk merujuk ke kelas bertingkat, bidang, metode, atau konstruktor, yaitu untuk semua anggota kelas tingkat tinggi kecuali blok inisialisasi dan komentar.
3. Istilah komentar selalu mengacu pada komentar implementasi. Kami tidak menggunakan frase "komentar dokumentasi", melainkan menggunakan istilah "Javadoc"

Terminologi lainnya akan disediakan sesuai kebutuhan di seluruh manual ini.

1.2 Catatan panduan

Contoh kode dalam dokumen ini tidak menunjukkan satu-satunya pendekatan gaya yang benar untuk pemformatannya, meskipun digunakan dalam tutorial kami.

2. File sumber. Dasar

2.1 Nama file

Nama file sumber terdiri dari nama satu kelas tingkat atas tertentu yang berada di dalamnya. Nama peka huruf besar dan kecil dan diakhiri dengan ekstensi .java

2.2 Pengkodean file: UTF-8

File dengan kode dikodekan dalam UTF-8.

2.3 Karakter khusus

2.3.1 Karakter spasi

Terlepas dari urutan karakter akhir baris, karakter spasi ASCII horizontal (0x20) adalah satu-satunya karakter pembatas yang ditemukan di file sumber. Artinya:

1. Semua karakter spasi kosong lainnya dalam karakter dan string literal di-escape
2. Karakter tab tidak digunakan untuk indentasi

2.3.2 Urutan pelarian khusus

Untuk setiap karakter yang memiliki urutan escape khusus (\ b, \ t, \ n, \ f, \ r, \ ", \ 'dan \\), lebih disukai untuk menggunakannya daripada nilai oktalnya yang sesuai (misalnya, \ 012 ) atau kode Unicode (misalnya \ u000a).

2.3.3 Karakter Non-ASCII

Untuk karakter non-ASCII, gunakan karakter Unicode (misalnya, ∞) atau urutan escape yang setara (misalnya, \ u221e). Pilihan dibuat untuk simbol-simbol yang membuat kode lebih mudah dipahami dan dibaca.

Saat menggunakan karakter escape Unicode dan dalam kasus di mana karakter Unicode yang valid digunakan, kami sangat menyarankan agar kode tersebut disertai dengan komentar penjelasan.

Jangan pernah membuat kode Anda kurang terbaca hanya karena takut beberapa program tidak dapat memproses karakter non-ASCII dengan benar. Jika ini terjadi, program tersebut tidak berfungsi dengan benar dan perlu diperbaiki.

3. Struktur file sumber

File sumber terdiri dari elemen-elemen berikut (dalam urutan yang ditunjukkan):

1. Informasi lisensi atau hak cipta, jika ada
2. Deklarasi paket
3. Mendeklarasikan impor
4. Deklarasi kelas

Tepat satu baris kosong memisahkan setiap bagian yang ada.

3.1 Lisensi atau informasi hak cipta, jika ada

Informasi lisensi atau hak cipta harus disertakan dalam file yang dirujuknya.

3.2 Deklarasi paket

Paket dideklarasikan tanpa jeda baris. Batasan lebar garis (Bagian 4.4) tidak berlaku untuk deklarasi paket.

3.3 Deklarasi impor

3.3.1 Karakter pengganti dalam deklarasi impor

Karakter * (wildcard) tidak digunakan saat mendeklarasikan impor, statis atau tidak.

3.3.2 Jeda baris

Impor dideklarasikan tanpa jeda baris. Mereka tidak tunduk pada batas lebar garis.

3.3.3 Penataan dan jarak

Impor dipesan sebagai berikut:

1. Semua impor statis ditempatkan dan dikelompokkan dalam satu blok
2. Semua impor non-statis ditempatkan di blok lain

Jika impor statis dan non-statis dideklarasikan, blok ini harus dipisahkan oleh baris kosong. Tidak boleh ada baris kosong lainnya di antara mereka.



Di dalam setiap blok, kelas yang diimpor dicantumkan dalam urutan penyortiran karakter ASCII.

3.3.4 Impor statis kelas bersarang

Impor statis tidak digunakan untuk kelas bertingkat statis. Kelas seperti itu diimpor dengan deklarasi impor biasa.

3.4 Deklarasi kelas

3.4.1 Tepat satu kelas tingkat atas dideklarasikan

Setiap kelas tingkat atas terletak di file sumbernya sendiri.

3.4.2 Mengurutkan konten kelas

Urutan tempat Anda menempatkan anggota dan blok inisialisasi kelas dapat berdampak besar pada seberapa mudah kode Anda dipahami. Bagaimanapun, tidak ada resep yang sederhana dan benar untuk ini; kelas yang berbeda dapat mengatur konten mereka secara berbeda.



Yang penting setiap kelas memiliki urutan logis dari konten sehingga programmer yang membaca kode dapat menjelaskannya.

3.4.2.1 Kode yang kelebihan beban tidak boleh dibagi

Jika kelas memiliki beberapa konstruktor atau metode dengan nama yang sama, mereka harus ditempatkan secara berurutan tanpa memasukkan kode lain di antaranya.

4. Pemformatan

Terminologi

Tubuh kelas, metode, atau konstruktor adalah konstruksi blok .



Perhatikan bahwa menurut Bagian 4.8.3.1, penginisialisasi larik apa pun juga dapat dianggap sebagai konstruksi blok.

4.1 Kawat gigi keriting

4.1.1 Kawat gigi keriting digunakan di mana pun mereka dapat digunakan

Tanda kurung kurawal digunakan di if, else, for, while, dan do-while, bahkan jika isi ekspresi kosong atau hanya berisi satu baris kode.

4.1.2 Blok Tidak Kosong: Gaya K&R

Tanda kurung kurawal ditempatkan sesuai dengan gaya Kernighan dan Ritchie ("tanda kurung Mesir") untuk blok yang tidak kosong dan struktur blok (untuk kejelasan, kami memutuskan untuk menambahkan sedikit kode yang mendemonstrasikan aturan ini - catatan penerjemah):

• Tidak ada pemutusan baris yang dilakukan sebelum kurung buka:

// 
if (true) { 

// 
if (true)
{

• Jeda baris dilakukan setelah kurung buka:

// 
while (true) {
  // code

// 
while (true) { // code

• Jeda baris dilakukan sebelum kurung tutup:

// 
for () {
  // code
}

// 
while (true) { /* code */ }

// 
if (true) {
  /* code */ }

• Jeda baris terjadi setelah kurung tutup hanya jika tanda kurung tersebut mengakhiri ekspresi atau isi metode, konstruktor, atau kelas non-anonim. Jeda baris tidak dilakukan setelah tanda kurung jika diikuti oleh else, catch atau titik koma

Contoh aturan yang dijalankan dengan benar:

return () -> {
  while (condition()) {
    method();
  }
};

return new MyClass() {
  @Override public void method() {
    if (condition()) {
      try {
        something();
      } catch (ProblemException e) {
        recover();
      }
    } else if (otherCondition()) {
      somethingElse();
    } else {
      lastThing();
    }
  }
};

Beberapa pengecualian untuk pencacahan diberikan dalam Bagian 4.8.1

4.1.3 Blok kosong dapat dikompresi

Blok kosong atau konstruksi blok kosong bisa mengikuti gaya K & R (seperti yang dijelaskan di Bagian 4.1.2). Ini juga mungkin untuk blok seperti itu untuk segera ditutup setelah dibuka, tanpa karakter atau jeda baris di dalamnya {}. Aturan ini tidak berlaku ketika blok adalah bagian dari ekspresi multi-blok yang berisi if-else atau try-catch-akhirnya.



Contoh:

// 
void doNothing() {}

//  
void doNothingElse() {
}

// :       
try {
  doSomething();
} catch (Exception e) {}

4.2 Dua spasi untuk lekukan

Setiap kali blok baru atau konstruksi blok dibuka, offset ke kanan bertambah dua spasi. Ketika blok berakhir, awal baris kode berikutnya bergeser ke level offset sebelumnya. Tingkat offset berlaku untuk blok dan komentar di blok itu (lihat contoh di Bagian 4.1.2).

4.3 Satu ekspresi per baris

Setiap ekspresi diakhiri dengan jeda baris.

4.4 Membatasi lebar garis hingga 100 karakter

Kode Java dibatasi hingga 100 karakter dalam lebar baris. Sebuah "karakter" mengacu pada salah satu elemen Unicode. Kecuali seperti yang dijelaskan di bawah, setiap garis yang melebihi batas lebar harus digabungkan seperti yang dijelaskan di Bagian 4.5.



Pengecualian:

1. , (, URL Javadoc JSNI- )
2. package import (. 3.2 3.3)
3. ,

4.5

Ketika kode yang mungkin berada di baris yang sama dibagi menjadi beberapa baris, fenomena ini disebut jeda baris.



Tidak ada rumus ambigu yang diterima secara umum yang menentukan dengan tepat bagaimana jeda baris harus dilakukan dalam setiap situasi. Seringkali ada beberapa cara untuk memutuskan baris dengan potongan kode yang sama.



Biasanya pembungkusan dilakukan untuk menghindari luapan lebar garis. Tetapi bahkan jika kode akan tetap berada dalam lebar yang diizinkan, maka, atas keputusan pembuatnya, kode dapat digabungkan ke baris baru.

Mengalokasikan metode pembantu atau variabel lokal dapat menyelesaikan masalah luapan lebar garis tanpa membungkus kode

4.5.1 Tempat untuk mentransfer

Pedoman pertama untuk jeda baris mengatakan: lebih baik melakukan jeda baris pada tingkat sintaksis yang lebih tinggi. Juga:



1. Ketika sebuah baris diputus pada pernyataan non-penugasan, pemutusan dibuat sebelum karakter.



Aturan ini juga berlaku untuk karakter "seperti operator" berikut:

• titik pemisah "."
• titik dua ganda dari metode referensi "::"
• ampersand dalam tanda kurung generik <T extends Foo & Bar>
• pembatas di blok catch (FooException | BarException e)

2. Ketika string dibungkus dalam pernyataan tugas, pembungkus biasanya dilakukan setelah karakter, tetapi solusi lain dapat diterima



Ini juga berlaku untuk titik dua untuk setiap loop.



3. Nama metode atau konstruktor ketika jeda baris tetap melekat pada tanda kurung buka "("



4. Koma "," jika pemisah baris tetap dengan elemen yang mendahuluinya



5. Garis tidak pernah dibungkus langsung di panah ekspresi lambda, kecuali jika tubuhnya terdiri dari satu ekspresi tanpa tanda kurung kurawal:

MyLambda<String, Long, Object> lambda =
    (String label, Long value, Object obj) -> {
        ...
    };

Predicate<String> predicate = str ->
    longExpressionInvolving(str);

Tujuan utama pemutusan baris adalah untuk mencapai kejelasan dalam kode, tetapi tidak harus dalam jumlah baris terkecil

4.5.2 Kelanjutan garis offset dengan 4 spasi atau lebih

Saat baris baru terputus, setiap substring berikutnya (setiap baris lanjutan) digeser setidaknya 4 spasi relatif terhadap yang sebelumnya.



Jika ada beberapa baris lanjutan, offset dapat bervariasi dalam 4 spasi atas permintaan penulis. Sebagai aturan umum, dua ekstensi baris dapat memiliki offset yang sama jika dan hanya jika dimulai dengan elemen paralel sintaksis.



Bagian 4.6.3 memberikan panduan tentang penggunaan jumlah spasi putih yang bervariasi untuk menyelaraskan titik kode dengan baris sebelumnya.

4.6 Spasi dan indentasi

4.6.1 Indentasi

Satu baris kosong selalu ditempatkan:



1. Di antara anggota yang berurutan atau penginisialisasi kelas: bidang, konstruktor, metode, kelas bersarang, blok inisialisasi statis dan dinamis

• pengecualian: baris kosong antara dua bidang yang berurutan (tidak ada kode di antara keduanya) adalah opsional. Baris kosong digunakan untuk mengelompokkan bidang secara logis jika perlu
• pengecualian: baris kosong antara konstanta kelas enum (lihat Bagian 4.8.1)

2. Konsisten dengan bagian lain dari dokumen ini (misalnya Bagian 3 dan Bagian 3.3) Baris



kosong juga dapat digunakan di semua tempat untuk meningkatkan keterbacaan kode, misalnya antara ekspresi untuk mengatur kode ke dalam subbagian logis. String kosong sebelum anggota pertama kelas, atau blok inisialisasi, atau setelah anggota terakhir, atau blok inisialisasi kelas tidak disarankan, tetapi tidak dilarang.



Beberapa baris kosong berurutan diizinkan, tetapi tidak perlu atau dianjurkan.

4.6.2 Spasi

Terlepas dari persyaratan bahasa itu sendiri atau aturan lain dari dokumen ini, serta tidak menghitung literal dan komentar (termasuk Javadoc), spasi tunggal dari tabel ASCII hanya dapat ditampilkan di tempat berikut:



1. Saat memisahkan kata yang dicadangkan seperti jika, untuk atau menangkap dan tanda kurung buka "(" yang mengikuti



2. Saat memisahkan kata yang dipesan, seperti else atau catch, dan tanda kurung kurawal penutup "}" yang mengikuti



3. Sebelum tanda kurung kurawal buka " {", Kecuali untuk dua situasi:

• @SomeAnnotation ({a, b})
• String [] [] x = {{"foo"}}; - spasi antara {{tidak diperlukan menurut klausul 8 di bawah

4. Di kedua sisi operator biner atau terner



Aturan ini juga berlaku untuk operator berikut:

• tanda dan tanda kurung sudut dalam: <T extends Foo & Bar>
• pembatas dalam blok catch yang berisi beberapa pengecualian: catch (FooException | BarException e)
• titik dua ":" di untuk masing-masing
• panah dalam ekspresi lambda: (String str) -> str.length ()

Tetapi aturan ini tidak berlaku untuk operator:

• titik dua ganda "::" dari metode referensi, yang ditulis sebagai Object :: toString
• titik pemisah ".", yang ditulis sebagai object.toString ()

5. Setelah ",:;" atau tanda kurung penutup ")" saat mentransmisikan ke tipe



6. Di kedua sisi garis miring ganda "//" saat membuat komentar pada baris kode yang sama. Beberapa spasi diperbolehkan tetapi tidak diperlukan di sini



7. Di antara deklarasi tipe dan nama variabel:

List<String> list

8. Opsional: di dalam tanda kurung penginisialisasi array

new int [] {5, 6} dan new int [] {5, 6} valid



9. Antara anotasi tipe dan [] atau ...



Aturan ini tidak memerlukan ada atau tidaknya spasi di awal atau akhir baris; itu hanya berlaku untuk ruang internal.

4.6.3 Penjajaran horizontal tidak pernah diperlukan

Terminologi

Perataan horizontal adalah praktik menambahkan sejumlah spasi ekstra dalam kode Anda untuk membuat elemen tertentu muncul di bawah elemen lain dari baris sebelumnya.



Praktik ini diizinkan tetapi tidak diwajibkan oleh panduan ini. Juga tidak perlu mempertahankan keselarasan di bagian-bagian kode yang telah diterapkan.



Contoh dengan dan tanpa perataan:

private int x; // 
private Color color; //   

private int   x;      // ,     
private Color color;  //    

Penjajaran meningkatkan keterbacaan kode, tetapi menimbulkan masalah dengan pemeliharaan kode tersebut di masa mendatang. Katakanlah Anda hanya ingin mengubah satu baris. Perubahan ini dapat merusak pemformatan kode yang diterima sebelumnya, yang dapat diterima. Tetapi, kemungkinan besar, pemrogram (mungkin Anda) akan mulai menyesuaikan jumlah spasi pada baris yang berdekatan, yang dapat memicu serangkaian koreksi. Mengubah satu baris dapat memicu "gelombang ledakan" tenaga kerja tanpa pikiran (paling buruk). Atau, paling banter, ini akan mengubah informasi dalam riwayat versi, mengganggu keterbacaan kode dan memperburuk konflik penggabungan.

4.7 Direkomendasikan tanda kurung pengelompokan

Anda hanya boleh menghilangkan tanda kurung pengelompokan jika penulis kode dan pengulas setuju bahwa tidak ada kemungkinan yang masuk akal bahwa kode akan disalahartikan tanpa tanda kurung, dan tanda kurung tidak akan membuatnya lebih mudah untuk dibaca. Tidak ada alasan untuk percaya bahwa siapa pun yang membaca kode tersebut telah menghafal seluruh tabel prioritas operator Java.

4.8 Desain khusus

4.8.1 Kelas pencacahan

Setelah setiap koma yang mengikuti konstanta pencacahan, jeda baris adalah opsional. Baris kosong ekstra (biasanya hanya satu) juga diperbolehkan. Berikut contoh kode tersebut:

private enum Answer {
  YES {
    @Override public String toString() {
      return "yes";
    }
  },

  NO,
  MAYBE
}

Kode kelas enumerasi tanpa metode dan komentar yang menjelaskan konstanta dapat direpresentasikan sebagai penginisialisasi array (lihat Bagian 4.8.3.1):

private enum Suit { CLUBS, HEARTS, SPADES, DIAMONDS }

Karena enum adalah kelas, semua aturan lain yang berlaku untuk kelas harus diterapkan padanya.

4.8.2 Deklarasi variabel

4.8.2.1 Satu variabel per deklarasi

Setiap variabel (bidang atau lokal) dideklarasikan hanya satu per satu: deklarasi seperti int a, b; tidak digunakan.



Pengecualian : Beberapa deklarasi variabel diperbolehkan di header for loop.

4.8.2.2 Deklarasikan variabel saat Anda membutuhkannya

Variabel lokal tidak harus dideklarasikan di awal konstruksi blok atau blok. Sebaliknya, variabel lokal perlu dideklarasikan sebelum digunakan pertama kali untuk meminimalkan ruang lingkupnya. Biasanya variabel lokal diinisialisasi pada saat deklarasi, atau segera setelahnya.

4.8.3 Array

4.8.3.1 Penginisialisasi array dapat "diblokir"

Setiap array dapat diinisialisasi seolah-olah itu adalah konstruksi blok. Misalnya, semua kode berikut ini valid (daftar contoh tidak lengkap):

new int[] {
  0, 1, 2, 3
}
                        
new int[] {
  0, 1,
  2, 3
}

new int[]
    {0, 1, 2, 3}

new int[] {
  0,
  1,
  2,
  3
}

4.8.3.2 Tidak ada deklarasi array gaya C.

Tanda kurung siku ditempatkan setelah jenis, bukan setelah variabel: String [] args, bukan String args [].

4.8.4 Pernyataan sakelar

Terminologi

Satu atau lebih grup pernyataan berada di dalam blok sakelar. Setiap grup terdiri dari satu atau lebih label (baik huruf FOO: dan default :) diikuti oleh satu atau lebih pernyataan (atau, dalam kasus kelompok terakhir, tidak ada atau lebih).

4.8.4.1 Offset

Seperti halnya blok lainnya, konten blok sakelar diimbangi dengan 2 spasi.



Jeda baris dibuat setelah label blok saklar, dan offset bertambah 2 spasi, sama seperti saat blok dibuka. Setiap label berikutnya kembali ke tingkat offset sebelumnya, seperti saat menutup satu blok.

4.8.4.2 Pass-through diberi komentar

Dalam satu blok, setiap grup pernyataan berakhir lebih cepat dari jadwal dengan sakelar (menggunakan jeda, lanjutkan, kembali, atau lempar pengecualian), atau ditandai dengan komentar untuk menunjukkan bahwa eksekusi kode akan atau dapat dilanjutkan di grup berikutnya. Setiap komentar yang menyampaikan gagasan melalui bagian (biasanya // gagal) sudah cukup. Komentar ini tidak diperlukan di grup terakhir dari blok sakelar. Contoh:

switch (input) {
  case 1:
  case 2:
    prepareOneOrTwo();
    // fall through
  case 3:
    handleOneTwoOrThree();
    break;
  default:
    handleLargeNumber(input);
}

Harap dicatat bahwa komentar tidak ditempatkan setelah kasus 1, tetapi hanya di akhir grup pernyataan.

4.8.4.3 Selalu gunakan default

Pernyataan switch harus berisi label default, meskipun tidak ada kode di dalamnya.



Pengecualian : Blok switch untuk tipe enum tidak boleh menggunakan default jika berisi kasus eksplisit yang mencakup semua kemungkinan nilai dari tipe itu. Hal ini memungkinkan IDE atau alat analisis statis lainnya untuk mengeluarkan peringatan bahwa beberapa kasus tidak tercakup.

4.8.5 Penjelasan

Anotasi yang diterapkan ke kelas, metode, atau konstruktor mengikuti segera setelah blok doc. Setiap anotasi ditunjukkan pada barisnya sendiri (yaitu, satu anotasi per baris). Jeda baris ini bukan pemisah baris (lihat Bagian 4.5), jadi level indentasi tidak dinaikkan. Contoh:

@Override
@Nullable
public String getNameIfPresent() { ... }

Pengecualian : anotasi tunggal tanpa parameter dapat ditampilkan bersama dengan baris tanda tangan pertama, misalnya:

@Override public int hashCode() { ... }

Anotasi yang diterapkan ke bidang juga muncul segera setelah blok dokumen, tetapi dalam kasus ini beberapa anotasi (mungkin berparameter) dapat dicantumkan dalam satu baris, misalnya:

@Partial @Mock DataLoader loader;

Tidak ada aturan khusus untuk memformat anotasi untuk parameter, variabel lokal, atau tipe.

4.8.6 Komentar

Bagian ini didedikasikan untuk komentar implementasi. Javadoc dibahas secara terpisah di Bagian 7.



Hentian baris apa pun dapat diawali dengan sejumlah spasi, diikuti dengan komentar implementasi. Komentar ini membuat baris tidak kosong.

4.8.6.1 Blok gaya komentar

Tingkat indentasi dari komentar blok sama dengan kode di sekitarnya. Blokir komentar dapat berupa / *… * / atau //… Untuk komentar banyak baris seperti / *… * /, baris berikutnya harus dimulai dengan *, disejajarkan dengan * dari baris sebelumnya.

/*
 * This is          // And so           /* Or you can
 * okay.            // is this.          * even do this. */
 */

Komentar tidak diapit dalam persegi panjang yang diwakili oleh tanda bintang atau simbol lainnya.

Saat menulis komentar beberapa baris, gunakan / * ... * / style jika Anda ingin pemformat kode otomatis memutus baris sesuai kebutuhan (gaya paragraf). Kebanyakan pemformat tidak dapat melakukan ini dengan blok komentar baris tunggal // ...

4.8.7 Pengubah

Pengubah kelas dan bidang, jika ada, ditampilkan dalam urutan yang direkomendasikan oleh spesifikasi bahasa Java:

public protected private abstract default static final transient volatile synchronized native strictfp

4.8.8 Literal numerik

Tipe panjang menggunakan huruf L besar, bukan huruf kecil (agar tidak tertukar dengan angka 1). Misalnya, 300_000_000L, bukan 300_000_000l.

5. Penamaan

5.1 Aturan umum untuk semua pengenal

Pengenal hanya menggunakan huruf dan angka ASCII dan, dalam beberapa kasus yang disebutkan di bawah, garis bawah.



Jadi, setiap nama pengenal yang valid cocok dengan ekspresi reguler \ w + (karakter alfanumerik yang muncul satu kali atau lebih).



Nama yang menggunakan sufiks atau prefiks khusus, seperti name_, mName, s_name, atau kName, tidak sesuai dengan gaya tutorial ini.

5.2 Aturan untuk berbagai jenis pengidentifikasi

5.2.1 Nama paket

Nama paket harus ditulis dengan huruf kecil, tanpa camelCase atau setrip bawah.



Benar: com.example.deepspace

Salah: com.example.deepSpace atau com.example.deep_space

5.2.2 Nama kelas

Nama kelas ditulis dengan gaya UpperCamelCase (huruf besar pertama).



Nama kelas biasanya berupa kata benda atau frase kata benda. Misalnya, Character atau ImmutableList.



Nama antarmuka juga dapat berupa kata benda atau frasa kata benda (misalnya, Daftar), tetapi terkadang juga dapat berupa kata sifat atau kombinasi kata sifat (misalnya, Dapat Dibaca).



Tidak ada aturan khusus atau bahkan konvensi yang mapan untuk penamaan jenis anotasi.



Kelas pengujian memiliki nama yang dimulai dengan nama kelas yang mereka uji dan diakhiri dengan Test. Misalnya, HashTest atau HashIntegrationTest.

5.2.3 Nama metode

Nama metode ditulis dengan gaya lowerCamelCase.



Nama metode biasanya kata kerja atau frase kata kerja. Misalnya sendMessage atau stop.



Garis bawah dapat digunakan dalam nama metode pengujian JUnit untuk memisahkan komponen logika dalam nama. Selain itu, setiap komponen ditulis dengan gaya lowerCamelCase. Pola tipikal adalah:

<methodUnderTest>_<state>, , pop_emptyStack

Tidak ada satu cara yang benar untuk memberi nama metode pengujian.

5.2.4 Nama konstan

Konstanta diberi nama dengan gaya CONSTANT_CASE: semua huruf adalah huruf besar, setiap kata dipisahkan oleh garis bawah. Tapi apa sebenarnya konstanta itu?



Konstanta adalah kolom final statis yang isinya tidak dapat diubah, dan metode yang tidak memiliki efek samping yang terlihat. Ini berlaku untuk primitif, String, tipe yang tidak bisa diubah, dan koleksi tipe yang tidak bisa diubah. Jika ada keadaan objek yang dapat diamati dapat berubah, itu bukan konstanta. Niat sederhana untuk tidak pernah memodifikasi suatu objek tidaklah cukup.



Contoh:

// 
static final int NUMBER = 5;
static final ImmutableList<String> NAMES = ImmutableList.of("Ed", "Ann");
static final ImmutableMap<String, Integer> AGES = ImmutableMap.of("Ed", 35, "Ann", 32);
static final Joiner COMMA_JOINER = Joiner.on(','); // because Joiner is immutable
static final SomeMutableType[] EMPTY_ARRAY = {};
enum SomeEnum { ENUM_CONSTANT }

//  
static String nonFinal = "non-final";
final String nonStatic = "non-static";
static final Set<String> mutableCollection = new HashSet<String>();
static final ImmutableSet<SomeMutableType> mutableElements = ImmutableSet.of(mutable);
static final ImmutableMap<String, SomeMutableType> mutableValues =
    ImmutableMap.of("Ed", mutableInstance, "Ann", mutableInstance2);
static final Logger logger = Logger.getLogger(MyClass.getName());
static final String[] nonEmptyArray = {"these", "can", "change"};

Nama konstan biasanya kata benda atau frase kata benda.

5.2.5 Nama bidang non-konstan

Nama kolom yang bukan konstanta (statis atau tidak) ditulis dengan gaya lowerCamelCase.



Nama-nama bidang tersebut biasanya kata benda atau frase kata benda. Misalnya, computedValues ​​atau index.

5.2.6 Nama parameter

Nama parameter ditulis dengan gaya lowerCamelCase.



Nama parameter satu karakter harus dihindari dalam metode publik.

5.2.7 Nama variabel lokal

Nama variabel lokal ditulis dengan gaya lowerCamelCase.



Meskipun bersifat final dan tidak dapat diubah, variabel lokal tidak dianggap konstanta dan tidak boleh ditulis dengan gaya yang sama seperti konstanta.

5.2.8 Nama variabel tipe

Setiap jenis variabel diberi nama menurut salah satu dari dua gaya:

• Huruf kapital tunggal, yang dapat diikuti dengan angka biasa (misalnya, E, T, X, T2)
• Nama dalam bentuk nama kelas (lihat Bagian 5.2.2) diikuti dengan huruf besar T (contoh: RequestT, FooBarT).

5.3 Model unta (CamelCase)

Terkadang ada lebih dari satu cara untuk mengonversi frasa bahasa Inggris menjadi gaya unta, seperti dalam kasus singkatan atau ekspresi atipikal seperti "IPv6" atau "iOS".



Untuk meningkatkan prediktabilitas, panduan ini menetapkan skema (contoh) berikut.



Dimulai dengan bentuk asli dari nama:



1. Ubah frasa menjadi ASCII biasa dan hapus semua apostrof. Misalnya, "Algoritme Müller" dapat diubah menjadi "Algoritme Muellers"



2. Bagi hasilnya menjadi kata-kata, buang spasi dan tanda baca yang tersisa (biasanya tanda hubung):

• rekomendasi: jika ada kata yang sudah memiliki bentuk umum dalam gaya "unta" yang biasa, bagi menjadi beberapa bagian komponennya (misalnya, "AdWords" diubah menjadi "kata-kata iklan"). Perhatikan bahwa kata seperti "iOS" sebenarnya bukan gaya unta; tidak sesuai dengan konvensi mana pun, jadi rekomendasi ini tidak berlaku.

3. Sekarang ubah semuanya menjadi huruf kecil (termasuk singkatan), lalu ubah ke huruf besar menjadi karakter pertama:

• ... di setiap kata untuk mencapai gaya UpperCamelCase, atau
• ... di setiap kata kecuali yang pertama mencapai gaya lowerCamelCase

4. Terakhir, gabungkan semua kata menjadi satu pengenal.



Perhatikan bahwa kasus dari kata asli hampir sepenuhnya diabaikan.



Contoh:



* Diizinkan tetapi tidak direkomendasikan.



Catatan : beberapa kata dalam bahasa Inggris menggunakan tanda hubung secara ambigu: misalnya, "nonempty" dan "non-empty" sudah benar, sehingga nama metode checkNonempty dan checkNonEmpty juga benar.

6. Praktek Pemrograman

6.1 Selalu gunakan anotasi @Override

Metode ini ditandai dengan anotasi @Override setiap kali sebenarnya diganti. Ini berlaku baik untuk metode kelas turunan yang menggantikan metode kelas induk, dan metode antarmuka yang menggantikan metode antarmuka super.



Pengecualian : anotasi dapat dihilangkan jika metode induk ditandai dengan anotasi @Deprecated.

6.2 Jangan abaikan pengecualian yang tertangkap

Sangat jarang ada situasi ketika Anda tidak perlu mengambil tindakan apa pun sebagai respons terhadap pengecualian yang tertangkap (solusi umumnya adalah dengan mencatatnya atau, jika dianggap "tidak mungkin", menampilkan pengecualian sebagai AssertionError).



Di bawah ini adalah contoh dengan komentar penjelasan ketika benar-benar tepat untuk tidak mengambil tindakan apa pun di blok tangkap:

try {
  int i = Integer.parseInt(response);
  return handleNumericResponse(i);
} catch (NumberFormatException ok) {
  // it's not numeric; that's fine, just continue
}
return handleTextResponse(response);

Pengecualian : Dalam pengujian, pengecualian yang tertangkap dapat diabaikan dan tidak diberi komentar jika nama pengujian diharapkan atau jika nama diawali dengan yang diharapkan. Berikut ini adalah idiom yang sangat umum yang menunjukkan bahwa kode yang diuji memunculkan pengecualian dari jenis yang diharapkan, jadi tidak ada komentar yang diperlukan di sini:

try {
  emptyStack.pop();
  fail();
} catch (NoSuchElementException expected) {
}

6.3 Untuk anggota statis, gunakan nama kelas

Anda perlu mengakses anggota kelas statis melalui nama kelas, dan bukan dengan mengacu pada objek kelas atau ekspresi yang mengembalikan objek ini:

Foo aFoo = ...;
Foo.aStaticMethod(); // 
aFoo.aStaticMethod(); // 
somethingThatYieldsAFoo().aStaticMethod(); //  

6.4 Jangan gunakan finalizer

Sangat jarang Anda perlu mengganti metode Object.finalize.



Petunjuk :



Jangan lakukan ini. Jika Anda benar-benar membutuhkannya, pertama-tama baca dan benar-benar pahami Efektif Java Item 7, “Hindari Finalizers,” dan kemudian jangan.

7. Javadoc

7.1 Pemformatan

7.1.1 Bentuk utama

Pemformatan sederhana dari blok Javadoc mengikuti contoh ini:

/**
 * Multiple lines of Javadoc text are written here,
 * wrapped normally...
 */
public int method(String p1) { ... }

... atau dalam satu baris:

/** An especially short bit of Javadoc. */

Bentuk sederhana selalu bisa diterapkan. Bentuk garis tunggal dapat diterapkan ketika seluruh blok Javadoc (termasuk penanda komentar) dapat dimuat dalam satu baris. Perhatikan bahwa ini hanya berlaku jika tidak ada tag seperti @return di blokir.

7.1.2 Paragraf

Satu baris kosong, yaitu baris yang hanya berisi tanda bintang di depan rata (*), muncul di antara paragraf dan sebelum grup tag blok, jika ada. Setiap paragraf kecuali yang pertama berisi <p> ​​tepat sebelum kata pertama, tanpa spasi setelahnya.

7.1.3 Memblokir tag

Semua tag blok berada dalam urutan ini: @param, @return, @throws, @deprecated, dan keempat jenis ini tidak pernah ada dengan deskripsi kosong. Jika tag blok tidak muat pada satu baris, baris lanjutan diberi indentasi empat (atau lebih) spasi dari @.

7.2 Cuplikan akhir

Setiap blok Javadoc dimulai dengan cuplikan ringkasan pendek. Cuplikan ini sangat penting: ini adalah satu-satunya teks yang muncul dalam konteks tertentu, seperti indeks kelas dan metode.



Potongan ini adalah kata benda atau frase kata kerja, bukan kalimat lengkap. Ini tidak dimulai dengan A {@code Foo} adalah ... atau Metode ini mengembalikan ..., juga tidak membentuk kalimat afirmatif lengkap seperti Save the record. Namun, bagian ini ditulis dengan huruf kapital dan diselingi seolah-olah itu adalah kalimat lengkap.



Petunjuk : Menulis Javadoc sederhana seperti / ** @return ID pelanggan * / merupakan kesalahan umum. Ini salah dan harus diperbaiki menjadi / ** Mengembalikan ID pelanggan. * /.

7.3 Kapan Javadoc Diterapkan

Javadoc hadir setidaknya di setiap kelas publik dan setiap anggota publik dan dilindungi dari kelas tersebut, kecuali dalam beberapa kasus, dijelaskan di bawah ini.

Javadoc tambahan mungkin ada, seperti yang dijelaskan dalam Bagian 7.3.4, Javadoc Opsional.

7.3.1 Pengecualian: metode yang menggambarkan diri mereka sendiri

Javadoc bersifat opsional untuk metode sederhana dan jelas seperti getFoo dalam kasus di mana Anda benar-benar tidak dapat mengatakan lebih dari "Mengembalikan foo".



Penting : Tidak tepat merujuk pada pengecualian ini untuk membenarkan penghilangan informasi relevan yang mungkin diperlukan oleh pembaca umum.



Misalnya, untuk metode bernama getCanonicalName, jangan menghilangkan dokumentasinya (dengan justifikasi bahwa nama metode hanya mengatakan / ** Mengembalikan nama kanonik. * /) Jika rata-rata orang yang membaca kode bahkan mungkin tidak mencurigai apa arti istilah "nama kanonik" !

7.3.2 Pengecualian: Mengesampingkan

Javadoc tidak selalu menyertai metode yang menggantikan metode dari kelas super (atau antarmuka super).

7.3.4 Javadoc opsional

Kelas dan anggota lain didampingi oleh Javadoc sesuai kebutuhan atau keinginan.



Setiap kali komentar implementasi akan digunakan untuk menentukan tujuan umum atau perilaku kelas atau anggota, komentar tersebut ditulis sebagai Javadoc (menggunakan / **).



Javadoc opsional tidak harus mengikuti aturan pemformatan Bagian 7.1.2, 7.1.3, dan 7.2, meskipun ini tentu saja direkomendasikan.



Terjemahan ini juga tersedia di blog kami .