Java kodlama en iyi uygulamalarının kısa bir özeti

Oracle, Google, Twitter ve Spring Framework kodlama standartlarına göre

Bu makalenin amacı, size hızlı bir özet yapmak ve başka bir deyişle, Oracle, Google, Twitter ve Spring Framework gibi teknoloji devlerinin kodlama standartlarını tercih etmekten kaçınmak değildir.

Burada sunulan en iyi uygulamaların bazılarına katılabilirsiniz veya katılmayabilirsiniz ve bazı kodlama standartları mevcut olduğu sürece bu kesinlikle iyi bir şeydir.

Neden her şeyden önce kodlama standartları? Google’ı seçerseniz, sizi aşağıdaki resimle birlikte bırakacağım için pek çok iyi neden var.

Kodlama standartları belgesi uzun ve sıkıcı olabilir. Bu makale, Google, Oracle, Twitter ve Spring tarafından kodlama sözleşmelerinden parça ve parçaları alır ve amacınız, kodunuzu okumasını ve bakımını kolaylaştırmak için izlemesi kolay ve daha az sıkıcı uygulamalar kümesi sağlamaktır.

Neredeyse her zaman mevcut yazılım üzerinde çalışan ekiplere katılacaksınız ve yazarların çoğunun farklı projelerden ayrılması veya farklı projelere geçmesi, sizi insanlığı sorgulamanıza neden olacak kod bölümleriyle mahsur bırakması konusunda oldukça iyi bir şans var.

Çeşitli kodlama standartlarından en iyi uygulamalara dalalım.

Java Kaynak Dosyası

Java kaynak dosyaları söz konusu olduğunda, aşağıdakiler en iyi yöntemler olarak kabul edilir:

  • Kaynak dosya uzunluğu 2.000 kod satırından düşük
  • Kaynak dosya, dokümantasyon yorumu, paket bildirimi, ardından bir sınıf yorumu, gruplandırılmış ithalat (son statik), sınıf / arayüz imzası vb.
paket com.example.model;
/ **
 * Geliştiriciler tarafından okunacak uygulama içermeyen bakış açısı
 * kaynak kodun elinizde olması gerekmeyebilir
 *
 * @author x, y, z
 * @tarih, randevu, biriyle çıkmak
 * @version
 * @copyright
 *
 * /
com.example.util.FileUtil dosyasını içe aktarın;
/ *
 * İsteğe bağlı sınıfa özel yorum
 *
 * /
genel sınıf SomeClass {
  // Görünürlük sırasına göre statik değişkenler
  genel statik son Tamsayı PUBLIC_COUNT = 1;
  statik son Tamsayı PROTECTED_COUNT = 1;
  özel statik final Tamsayı PRIVATE_COUNT = 1;
  // Görünürlük sırasına göre örnek değişkenleri
  public Dize adı;
  Dize postalCode;
  özel Dize adresi;
  // Yapıcı ve aşırı sırayla aşırı yüklenmiş
  genel SomeClass () {}
  public SomeClass (Dize adı) {
    this.name = isim;
  }
  // Yöntemler
  Genel Dize doSomethingUseful () {
    "Yararlı bir şey" döndür;
  }
  // getters, setters, eşittir, hashCode ve sonunda toString
}

Adlandırma

Sınıf ve arayüz adları CamelCase'dir ve kelimenin tamamını kullanmanız ve kısaltmalar / kısaltmalar yapmamanız önerilir. Örneğin sınıf Raster veya sınıf ImageSprite

  • Paket - com.deepspace yerine com.deepSpace veya com.deep_space isimleri
  • Dosya adları CamelCase'dir ve sınıf adıyla eşleşen .java ile biter. Her dosyada bir ortak sınıf var ve her bir üst sınıfta bir dosya var.
  • Yöntem - adlar, örneğin run (); veya runFast ();
  • Sabitler - her kelimeyi birbirinden ayıran "_" harfleri büyük olmalı, örneğin int MIN_WIDTH = 44; ve int MAX_WIDTH = 99;
  • Değişken - programın okuyucusuna değişkenin neyi temsil ettiğini söyleyen bir isim, yani eğer bir test notu saklıyorsanız, grade vs var1 seçimini yapın. Değişken isimlerini kısa tutun, meta veriler kullanmaktan kaçının.
// Prefer () - değişken isimleri kısa ve ne sakladığını açıklar
int okul kimliği;
int [] filtrelenmiş Okul İçi;
int [] uniqueSchooldIds;
Eşlem  usersById;
Dize değeri;
// Kaçının (x) - Çok detaylı değişken adlandırma
int schoolIdentificationNumber;
int [] userProvidedSchoolIds;
int [] schoolIdsAfterRemovingDuplicates;
Eşlem  idToUserMap;
Dize valueString;

Unutma - değişken ismi kısa olmalı ve okuyucuya hangi değeri temsil ettiğini kolayca söylemelidir. Kararını kullan.

Tercih Et ve Kaçının

Biçimlendirme ve girinti kodunuzu okumayı kolaylaştırmak için düzenlemekle ilgilidir ve boşluk, satır uzunluğu, sarmalar ve kesmeler vb. İçerir.

  • Girinti - 2 veya 4 boşluk kullanın ve tutarlı kalın
  • Satır uzunluğu - Okunabilirliğe bağlı olarak 70 - 120 karaktere kadar Bir virgül ve operatörden sonra yatay kaydırma ve satır kesmeleri yapma gereksinimini ortadan kaldırmak önemlidir.

Yöntemler - İşte en iyi uygulamaların bir listesi

// Tercih () Satır sonları keyfi ve virgülden sonra sonlanır.
Dize indirAnInternet (İnternet internet, Tüpler,
    Blogosfer blogları, Miktar  bant genişliği) {
  tubes.download (internet);
}
(2) Kaçınılması zor yöntem metodu gövdesine yaklaşıyor
Dize indirAnInternet (İnternet internet, Tüpler,
    Blogosfer blogları, Miktar  bant genişliği) {
    tubes.download (internet);
}
// Tercih () Derin girinti için 8 (iki veya 2 veya 4) boşluk ekleyin
özel statik senkronize horkingLongMethodName (int anArg,
        AnotherArg nesnesi, String yetAnotherArg,
        Object andStillAnother) {
  ...
}
// Tercih () Kolay tarama ve ekstra sütun alanı.
public Dize indirAnInternet (
    İnternet internet,
    Borular
    Blogosfer blogları,
    Miktar  bant genişliği) {
  tubes.download (internet);
  ...
}
Bir birim testi şunu yakalardı:

If-checks - IMO iyi biçimlendirilmiş kod yazmak, yazımcıları ve hataları yazara ve kod gözden geçirenlere bulmayı kolaylaştırır, aşağıya bakın:

// Kaçının (x) Atlamayın {}
eğer (koşul)
  Beyan;
// Kaçının (x)
eğer (x <0) negatif (x);
// Kaçının (x)
eğer (a == b && c == d) {
...
}
// Tercih ()
eğer ((a == b) && (c == d)) {
...
}
// Tercih ()
eğer (koşul) {
  ifadeleri;
} else eğer (koşul) {
  ifadeleri;
} else eğer (koşul) {
  ifadeleri;
}
// Kaçının (x)
eğer ((koşul1 ve & koşul2)
    || (koşul3 ve koşul 4)
    ||! (condition5 && condition6)) {// BAD WRAPS
    doSomethingAboutIt (); // BU HATTI ÖZELLEŞTİRMEYİ KOLAY YAPMAK
}
// Tercih ()
eğer ((koşul1 ve & koşul2)
        || (koşul3 ve koşul 4)
        ||! (condition5 && condition6)) {
    doSomethingAboutIt ();
}

Üçlü operatör - Ve aşağıda önerilen uygulamalar

alpha = (aLongBooleanExpression)? beta: gama;
alpha = (aLongBooleanExpression)? beta
        : gama;
alpha = (aLongBooleanExpression)
        ? beta
        : gama;

Geçiş Yap - Geçiş yapmanın en iyi yolu

  • Kod olmadan bile her zaman varsayılan bir durumda ol
  • Kontrolün bir sonraki duruma geçtiğini belirtmek için / * falls * / ile kullanın.
anahtar (koşul) {
  ABC harfini:
    ifadeleri;
  / * düşüyor * /
  Vaka DEF:
    ifadeleri;
    break;
  varsayılan:
    ifadeleri;
     break;
}

İstisna mesajları - Burada bir istisna atarken, iyi ve zayıf girintili mesajların örnekleridir.

// Kaçının (x) - Okunması kolay değil
yeni IllegalStateException ("istek işlenemedi" + request.getId ()
    + "kullanıcı için" + user.getId () + "query: '" + query.getText ()
    + "'");
// Tercih () - Okuması oldukça kolay
yeni IllegalStateException ("işlenemedi"
    + "request" + request.getId ()
    + "kullanıcı için" + user.getId ()
    + "query: '" + query.getText () + "'");

Yineleyiciler ve Akışlar - Akışlar daha yaygın hale gelir ve zaman zaman çok karmaşık olabilir, bu nedenle okunması kolay girintili olmak önemlidir.

// Kaçının (x) - Okunması kolay değil
Yinelenebilir  module = ImmutableList.  builder (). Add (new LifecycleModule ())
    .add (yeni AppLauncherModule ()). addAll (application.getModules ()). build ();
// Tercih () - Okuması oldukça kolay
Yinelenebilir  modülleri = ImmutableList.  builder ()
    .add (yeni LifecycleModule ())
    .add (yeni AppLauncherModule ())
    .addAll (application.getModules ())
    .inşa etmek();
Sadece bir kodlama standardına uyun - gerçekten

Beyanlar ve Ödevler - Her satırda bir beyan, aşağıda gösterildiği gibi yorumları teşvik ettiği için tavsiye edilir.

// Tercih ()
int seviyesi; // girinti seviyesi
int sizeMeter; // tablonun boyutu
// Yukarıdakilerden (x) kaçının
int seviyesi, sizeMeter;
// Tercih () - Birimi değişken adına veya türüne dahil et
uzun anketIntervalMs;
int fileSizeGb;
Miktar  fileSize;
// (x) karıştırma tiplerinden kaçının
int foo, fooarray [];
// Kaçının (x) - Virgül ile ayırmayın
Format.print (System.out, “hata”), çıkış (1);
// (x) çoklu atamadan kaçının
fooBar.fChar = barFoo.lchar = 'c';
// Performansı arttırma girişiminde (x) gömülü ödevlerden kaçının // veya bir satır kaydet. Bunu yapmaktan suçluyum :(
d = (a = b + c) + r;
// Yukarıda ()️) tercih et
a = b + c;
d = a + r;
// Tercih ()
Dize [] args
// Kaçının (x)
Dize args []
// Tercih () Uzun ile "l" yerine "L" kullanın.
uzun zaman aşımı = 3000000000L;
// Kaçının (x) - Son mektubu l ve 1 olmadığını söylemek zor
uzun zaman aşımı = 3000000000l;

Bildirimleri yalnızca blokların başına yerleştirin (Bir blok, küme parantezleriyle çevrili koddur {ve}). İlk kullanımına kadar değişkenleri bildirmeyi beklemeyin; istenmeyen programcıyı karıştırabilir ve kapsam dahilindeki taşınabilirliği engelleyebilir.

// Tercih edilen () bloğun başında bildirir.
kamu boşluğu doSomething () {
  int whatirepresent; // yöntem bloğunun başlangıcı
  eğer (koşul) {
    int someFlag; // “if” bloğunun başlangıcı
    ...
  }
}

Ayrıca, daha yüksek seviyelerin bildirimlerini gizleyen ve aşağıda gösterildiği gibi kafa karışıklıklarından kaçınmak için yerel bildirimlerden kaçınmak önemlidir.

int sayısı;
...
kamu boşluğu doSomething () {
  eğer (koşul) {
    int sayısı; // ÖNLEMEK!
    ...
  }
  ...
}

Boşluk ve satır sonları - Okunabilirlik pahasına 1-2 satırlık kod kaydetme isteğinden kaçının. Boşluk ve boş satırlar söz konusu olduğunda en iyi uygulamalar şunlardır (Beyaz boşluk fark yaratır)

  • Yöntemler ve Yay geliştiriciler arasındaki bir (1) boş satır, kuruculardan, statik bloktan, alanlardan ve iç sınıftan sonra iki (2) boş satır önerir.
  • Space pad operatörleri, yani int foo = a + b + 1; int foo = a + b + 1;
  • Bir boşluk kullanarak "." Dışındaki tüm ikili işleçleri işlenenlerden ayırma
  • Açık parantez “{”, bildirim ifadesi veya yöntemiyle aynı satırın sonunda görünür ve “}” parantez kapanışı kendiliğinden girintili bir satır başlatır
// Prefer () - "while" dan sonra ve "(" dan önce olan boşluk
while (true) {
  ...
}
// Kaçının (x) - Yukarıdakilerin aksine boşluk bırakmayın
while (true) {
  ...
}
// Tercih () - "doSomething" ve "(" arasında boşluk yok
kamu boşluğu doSomething () {
  ...
}
// Kaçının (x) - Yukarıdaki boşluğun aksine
kamu boşluğu doSomething () {
  ...
}
// Tercih () - Bir argümandan sonra boşluk ekle
public void doSomething (int a, int b) {
  ...
}
// Tercih () - İşlenen ve işleçler arasındaki boşluk (yani, +, =)
a + = c + d;
a = (a + b) / (c * d);
iken (d ++ = s ++) {
  N ++;
}

Belgeler ve Yorumlar

Neredeyse tüm kodların kullanım ömrü boyunca değiştiğinden ve sizin veya birisinin karmaşık bir kod bloğunun, bir yöntemin veya bir sınıfın açıkça açıklanmadığı sürece ne yapması gerektiğini anlamaya çalıştığı zamanlar olacağını belirtmekte fayda var. Gerçek neredeyse her zaman olduğu gibi

Karmaşık bir kod parçası, yöntem, sınıf hakkındaki yorumun hiçbir değer katmadığı veya amacına hizmet ettiği zamanlar vardır. Bu genellikle bunun uğruna yorum yaparken olur.

Yorumlar, kodun genel bir özetini vermek ve kodun kendi içinde hazır olmayan ek bilgiler sağlamak için kullanılmalıdır. Başlayalım. İki tür yorum var

Uygulama Yorumları - kodu yorumlamak veya kodun belirli bir uygulaması hakkında yorum yapmak içindir.

Belge Yorumları - kaynak kodunu mutlaka elinizde bulundurmayabilecek geliştiriciler tarafından okunması için, kodun özelliklerini uygulama gerektirmeyen bir bakış açısıyla tanımlamak içindir.

Yorum sıklığı bazen düşük kod kalitesini yansıtıyor. Bir yorum eklemek zorunda kaldığınızı hissettiğinizde, kodu daha net hale getirmek için yeniden yazmayı düşünün.

Uygulama Yorum Türleri

Aşağıda gösterildiği gibi dört (4) tür uygulama yorumu vardır

  • Yorumu engelle - aşağıdaki örneğe bakın
  • Tek satır yorumu - yorum bir satırdan uzun olmadığı zaman
  • İzleyen yorumlar - Çok kısa yorum sağa taşındı
  • Satır sonu yorum - yeni satıra devam eden bir yorum başlatır. Tam bir çizgi ya da sadece bir kısmi çizgi yorumlayabilir. Metin yorumları için ardışık çoklu satırlarda kullanılmamalıdır; ancak, kod bölümlerini yorumlamak için ardışık çoklu satırlarda kullanılabilir.
// Yorumu engelle
/ *
 * Kullanım: Dosyaların, yöntemlerin, veri yapılarının tanımını sağlar
 * ve algoritmalar. Her dosyanın başında kullanılabilir ve
 * Her yöntemden önce. Uymayan uzun yorumlar için kullanılır
 * tek çizgi. Blok yorumundan sonra devam etmek için 1 Boş satır.
 * /
// Tek satırlı yorum
eğer (koşul) {
 / * Koşulu idare et. * /
  ...
}
// İzleyen yorum
eğer (a == 2) {
 TRUE döndürür; /* özel durum */
} Başka {
 dönüş isPrime (a); / * sadece garip bir durum için çalışır * /
}
// Yorum satırının sonu
eğer (foo> 1) {
  // İkili çevirme yapın.
  ...
} Başka {
  false döndürmek; // Neden burada olduğunu açıkla.
}
// if (bar> 1) {
//
// // Üçlü kapak yap.
// ...
//}
//Başka
// false döndürmek;

Belge yorumları (yani Javadoc)

Javadoc, / ** ile başlayan ve * / ile biten yorumları kullanarak java kodunuzu oluşturan HTML dokümantasyonu oluşturan bir araçtır - Javadoc'un nasıl çalıştığı veya okuduğunu okumak için daha fazla ayrıntı için Wikipedia'ya bakın.

İşte bir Javadoc örneği

/ **
 * Sonra ekranda boyanabilecek bir Image nesnesi döndürür.
 * URL argümanı mutlak bir {@link URL} belirtmelidir. İsim
 * argümanı url argümanına göre olan bir özelliktir.
 * 

 * Bu yöntem her zaman derhal geri döner, ister olmasın  * görüntü var. Bu uygulama görüntüyü çizmeye çalıştığında  * Ekranda veri yüklenecek. Grafik ilkelleri  * Görüntüyü çizen ekranda adım adım boyayacaktır.  *  * @param url, görüntünün temel konumunu veren mutlak bir URL  * @param, url argümanına göre görüntünün konumunu adlandırır.  * @ resmi belirtilen URL’de göster  * @see Image  * /  public Image getImage (URL url, Dize adı) {         Deneyin {             getImage döndür (yeni URL (url, ad));         } catch (MalformedURLException e) {             null döndür;         }  }

Ve javadoc yukarıdaki kodlara karşı çalıştırıldığında yukarıdaki kod bir HTML ile sonuçlanır.

Daha fazlası için buraya bakın

Burada, oluşturulan java belgelerinin kalitesini artırmak için kullanabileceğiniz bazı anahtar etiketler verilmiştir.

@author => @author Raf
@code => {@code A  C}
@deprecated => @deprecated kullanımdan kaldırma mesajı
@exception => @exception IOException ne zaman atılmış
@link => {@link package.class # member etiketi}
@param => @param parametre adı açıklaması
@return => Yöntem ne döndürür?
@see => @see "string" OR @see  
@since => Herkese açık bir yöntem eklendiğinde sürümü belirtmek için

Tam bir liste ve daha ayrıntılı bir açıklama için buraya bakın

Twitter’ın kodlama standardı, @author etiketinin kullanılmasına karşı tavsiyede bulunur

Kod, yaşamı boyunca birçok kez el değiştirebilir ve kaynak kodun orijinal yazarı, birkaç yinelemeden sonra ilgisizdir. Bir kod kodunun sahipliğini belirlemek için taahhüt tarihi ve SAHİP dosyalarına güvenmenin daha iyi olduğunu düşünüyoruz.

Aşağıda, Twitter’ın kodlama standardında anlatıldığı gibi nasıl anlaşılır bir dokümantasyon yorumu yazabileceğinize örnekler

// Kötü.
// - Doktor, yöntem bildiriminin yapmadığını hiçbir şey söylemez.
// - Bu 'dolgu dosyası'. Stil kontrollerini geçecekti ama
kimseye yardım etmiyor.
/ **
 * Bir dize böler.
 *
 * @param s Bir dize.
 * @return Bir dizge listesi.
 * /
Liste  split (Dize);
// Daha iyi.
// - Yöntemin neye dağıldığını biliyoruz.
// - Hala bazı tanımsız davranışlar.
/ **
 * Boşlukta bir dize böler.
 *
 * @param s Bölünecek dize. Bir {@code null} dizesi boş bir dize olarak kabul edilir.
 * @return Girdinin boşlukla ayrılmış bölümlerinin listesi.
 * /
Liste  split (Dize);
// Harika.
// - Başka bir uç vakayı kapsar.
/ **
 * Boşlukta bir dize böler. Tekrarlanan boşluk karakterleri
 * çöktü.
 *
 * @param s Bölünecek dize. Bir {@code null} dizesi boş bir dize olarak kabul edilir.
 * @return Girdinin boşlukla ayrılmış bölümlerinin listesi.
 * /
Liste  split (Dize);

Yorum yazarken profesyonel olmak önemlidir.

// Kaçının (x)
// xml / soap'dan çok nefret ediyorum, neden bunu benim için yapamıyor?
Deneyin {
  userId = İnteger.parseInt (xml.getField ("id"));
} catch (NumberFormatException e) {
  ...
}
// Tercih ()
// TODO (Jim): Tuck bir alandaki kütüphanede doğrulama alanı.
Deneyin {
  userId = İnteger.parseInt (xml.getField ("id"));
} catch (NumberFormatException e) {
  ...
}

Uygulama değişmediyse geçersiz kılınan yöntemi belgelememek akılda tutulması önemlidir.

Ve burada akılda tutulması gereken birkaç nokta

  • Joker karakter ithalatından kaçının - Twitter’ın kodlama standartlarında açıklandığı gibi sınıfın kaynağını daha az belirgin hale getirir. Eclipse ve IntelliJ kullanıcılarının bir karışımını içeren bir ekipte çalışıyorum ve Eclipse’in joker karakter ithalatını kaldırdığını ve IntelliJ’in bunu tanıttığını öğrendim. Muhtemelen bunu kapatmak için bir seçenek vardır, sadece ikisi için varsayılanı işaret etmek istedim.
  • Geçersiz kıldığınızda, her zaman @Override notunu kullanın
  • Bir alan veya yöntem null döndürdüğünde @Nullable kullanımını teşvik etme
  • Gelecekteki çalışmalar için özel yorumlardan yararlanın ve kendinize bir referans bırakmayı unutmayın; böylece başkaları, kim eklemek istediğini tahmin etmek, çıkarmak veya Git suçunu kontrol etmek yerine, Y sorusunu kime soracaklarını bilir. Eclipse ve IntelliJ gibi bazı IDE'ler de kolay hatırlatmanın yanı sıra kolay erişim için listelemelerine yardımcı olur.
// FIXME (Raf): Yapılabilir bir mesaj ne yapılması gerektiğini açıklar
// TODO (Raf): Yapılabilir bir mesaj ne yapılması gerektiğini açıklar

Son oyun gelecekteki yazarların ve bakıcıların hayatını kolaylaştıran kod yazmaktır.

Sonu oyunu

Diğer ilgili okuma materyalleri

Temiz, iyi yapılandırılmış, okunması kolay ve bakımı kolay kod yazmayla ilgili makalelerin listesi. Daha fazla okumak istiyorsanız, aşağıdakileri kesinlikle önerin:

ve temiz kod yazmak için başka bir iyi ipucu listesi