Katkıda Bulunanlar için AOSP Java Kodu Stili

Bu sayfadaki kod stilleri, Java kodunu Android Açık Kaynak Projesine (AOSP) katkıda bulunmak için katı kurallardır. Genellikle kabul edilmeyen bu kurallara uymayan Android platformu Katkıları. Mevcut tüm kodların bu kurallara uymadığını biliyoruz, ancak tüm yeni kodların uyumlu olmasını bekliyoruz. Bkz Saygı ile Kodlama daha kapsayıcı ekosistem için kullanılacak terminoloji ve kaçınmak örnekleri için.

Tutarlı ol

En basit kurallardan biri TUTARLI OLUN. Kodu düzenliyorsanız, çevreleyen koda bakmak ve stilini belirlemek için birkaç dakikanızı ayırın. Bu kod etrafında boşluk kullanıyorsa if maddeleri, sen gerektiğini de. Kod yorumlarının çevresinde küçük kutucuklar varsa, yorumlarınızın da çevresinde küçük kutucuklar olsun.

Stil yönergelerine sahip olmanın amacı, ortak bir kodlama sözlüğüne sahip olmaktır, böylece okuyucular nasıl söylediğiniz yerine ne söylediğinize odaklanabilirler. Kelime dağarcığını bilmeniz için burada global stil kurallarını sunuyoruz, ancak yerel stil de önemlidir. Bir dosyaya eklediğiniz kod, etrafındaki mevcut koddan büyük ölçüde farklı görünüyorsa, okuyucuları okuduklarında ritmin dışına çıkarır. Bundan kaçınmaya çalışın.

Java dili kuralları

Android, aşağıda açıklanan ek kurallarla standart Java kodlama kurallarına uyar.

İstisnaları göz ardı etmeyin

Aşağıdaki gibi bir istisnayı yok sayan kod yazmak cazip gelebilir:

  void setServerPort(String value) {
      try {
          serverPort = Integer.parseInt(value);
      } catch (NumberFormatException e) { }
  }

Bunu yapma. Kodunuzun bu hata koşuluyla hiçbir zaman karşılaşmayacağını veya bununla başa çıkmanın önemli olmadığını düşünebilirsiniz, ancak bu tür bir istisnayı göz ardı etmek, bir gün başka birinin tetiklemesi için kodunuzda mayınlar oluşturur. Kodunuzdaki her istisnayı ilkeli bir şekilde ele almalısınız; özel kullanım duruma göre değişir.

"Ne zaman ki birileri onlar tüyler ürpertici bir duygu olmalıdır. Aslında yapmak doğru şeydir zamanlar kesinlikle vardır boş yakalamak şartı vardır, ama en azından bunu düşünmek zorundayız. In Java size ürpertici duygu kaçamaz. "- James Gosling

Kabul edilebilir alternatifler (tercih sırasına göre):

  • İstisnayı yönteminizin arayana kadar atın.
      void setServerPort(String value) throws NumberFormatException {
          serverPort = Integer.parseInt(value);
      }
    
  • Soyutlama seviyenize uygun yeni bir istisna atın.
      void setServerPort(String value) throws ConfigurationException {
        try {
            serverPort = Integer.parseInt(value);
        } catch (NumberFormatException e) {
            throw new ConfigurationException("Port " + value + " is not valid.");
        }
      }
    
  • İncelikle hata işlemek ve de uygun bir değer yerine catch {} bloğu.
      /** Set port. If value is not a valid number, 80 is substituted. */
    
      void setServerPort(String value) {
        try {
            serverPort = Integer.parseInt(value);
        } catch (NumberFormatException e) {
            serverPort = 80;  // default port for server
        }
      }
    
  • Özel durumu yakalamak ve yeni bir örneğini atmak RuntimeException . Bu tehlikelidir, bu nedenle, yalnızca bu hatanın meydana gelmesi durumunda yapılacak uygun şeyin çökme olduğundan eminseniz yapın.
      /** Set port. If value is not a valid number, die. */
    
      void setServerPort(String value) {
        try {
            serverPort = Integer.parseInt(value);
        } catch (NumberFormatException e) {
            throw new RuntimeException("port " + value " is invalid, ", e);
        }
      }
    
  • Son çare olarak, istisnayı görmezden gelmenin uygun olduğundan eminseniz, onu görmezden gelebilirsiniz, ancak bunun nedenini de iyi bir nedenle yorumlamalısınız.
    /** If value is not a valid number, original port number is used. */
    
    void setServerPort(String value) {
        try {
            serverPort = Integer.parseInt(value);
        } catch (NumberFormatException e) {
            // Method is documented to just ignore invalid user input.
            // serverPort will just be unchanged.
        }
    }
    

Genel istisnaları yakalama

İstisnaları yakalarken tembel olmak ve bunun gibi bir şey yapmak cazip gelebilir:

  try {
      someComplicatedIOFunction();        // may throw IOException
      someComplicatedParsingFunction();   // may throw ParsingException
      someComplicatedSecurityFunction();  // may throw SecurityException
      // phew, made it all the way
  } catch (Exception e) {                 // I'll just catch all exceptions
      handleError();                      // with one generic handler!
  }

Bunu yapma. Hemen hemen tüm durumlarda, jenerik yakalamak için uygunsuz Exception veya Throwable (tercihen değil Throwable o içerdiğinden Error istisnalar). O (gibi çalışma zamanı istisnaları da dahil olmak üzere, hiç beklemediğiniz o istisnalar demektir çünkü tehlikeli ClassCastException ) uygulama düzeyinde hata işleme sıkışabilir. Kodunuzun hata işleme özelliklerini gizler, yani biri aradığınız koda yeni bir istisna türü eklerse, derleyici hatayı farklı şekilde ele almanız gerektiğini belirtmez. Çoğu durumda, farklı istisna türlerini aynı şekilde ele almamalısınız.

Bu kuralın nadir istisnası, her türlü hatayı (bir kullanıcı arayüzünde görünmelerini önlemek veya bir toplu işin çalışmasını sağlamak için) yakalamak istediğiniz test kodu ve üst düzey koddur. Bu durumda, jenerik yakalayabilir Exception (veya Throwable ) ve uygun hatayı işlemek. Bunu yapmadan önce dikkatlice düşünün ve bu bağlamda neden güvenli olduğunu açıklayan yorumlar yazın.

Genel istisnaları yakalamanın alternatifleri:

  • Örneğin, bir çok-catch bloğunun bir parçası olarak ayrı ayrı her bir özel durum yakalamak:
    try {
        ...
    } catch (ClassNotFoundException | NoSuchMethodException e) {
        ...
    }
  • Birden çok deneme bloğuyla daha ayrıntılı hata işlemeye sahip olmak için kodunuzu yeniden düzenleyin. IO'yu ayrıştırmadan ayırın ve her durumda hataları ayrı ayrı ele alın.
  • İstisnayı yeniden atın. Çoğu zaman, yine de bu düzeyde istisnayı yakalamanız gerekmez, yöntemin onu atmasına izin verin.

İstisnaların arkadaşınız olduğunu unutmayın! Derleyici bir istisna yakalamadığınızdan şikayet ettiğinde, kaşlarını çatmayın. Gülümsemek! Derleyici, kodunuzdaki çalışma zamanı sorunlarını yakalamanızı kolaylaştırdı.

Sonlandırıcıları kullanmayın

Sonlandırıcılar, bir nesne çöp toplandığında yürütülecek bir kod yığınına sahip olmanın bir yoludur. Sonlandırıcılar temizlik için (özellikle dış kaynaklar için) kullanışlı olsa da, bir sonlandırıcının ne zaman çağrılacağına (hatta çağrılacağına) dair hiçbir garanti yoktur.

Android, sonlandırıcıları kullanmaz. Çoğu durumda, bunun yerine iyi özel durum işlemeyi kullanabilirsiniz. Kesinlikle bir finalizer gerekiyorsa, bir tanımlamak close() bu yöntem ihtiyacı (bkz çağrılacak tam olarak ne zaman yöntemi (veya benzeri) ve belgeyi InputStream bir örnek için). Bu durumda, günlükleri taşması beklenmediği sürece sonlandırıcıdan kısa bir günlük mesajı yazdırmak uygundur ancak gerekli değildir.

Tam nitelikli ithalat

Eğer sınıf kullanmak istediğinizde Bar paket dan foo , ithal etmek olası iki yolu vardır:

  • import foo.*;

    İçe aktarma ifadelerinin sayısını potansiyel olarak azaltır.

  • import foo.Bar;

    Hangi sınıfların kullanıldığını ve kodun bakımcılar için daha okunabilir olmasını sağlar.

Kullanım import foo.Bar; tüm Android kodunu içe aktarmak için. Bir açık istisna Java standart kütüphaneleri için yapılır ( java.util.* , java.io.* , vb) ve birim test kodu ( junit.framework.* ).

Java kitaplığı kuralları

Android'in Java kitaplıklarını ve araçlarını kullanma kuralları vardır. Bazı durumlarda, sözleşme önemli şekillerde değişmiştir ve eski kod, kullanımdan kaldırılmış bir kalıp veya kitaplık kullanabilir. Böyle bir kodla çalışırken, mevcut stile devam etmenizde bir sakınca yoktur. Ancak yeni bileşenler oluştururken, kullanımdan kaldırılmış kitaplıkları asla kullanmayın.

Java stili kuralları

Javadoc standart yorumlarını kullanın

Her dosyanın en üstünde bir telif hakkı bildirimi, ardından paket ve içe aktarma ifadeleri (her blok boş bir satırla ayrılmış) ve son olarak sınıf veya arayüz bildirimi olmalıdır. Javadoc yorumlarında, sınıfın veya arayüzün ne yaptığını açıklayın.

/*
 * Copyright 2021 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.android.internal.foo;

import android.os.Blah;
import android.view.Yada;

import java.sql.ResultSet;
import java.sql.SQLException;

/**
 * Does X and Y and provides an abstraction for Z.
 */

public class Foo {
    ...
}

Her sınıf ve en az bir cümle sınıf veya yöntem ne yaptığını açıklayan bir Javadoc yorumunu içermelidir yazmanızı nontrivial kamu yöntemi. Bu cümle üçüncü şahıs tanımlayıcı fiil ile başlamalıdır.

Örnekler

/** Returns the correctly rounded positive square root of a double value. */

static double sqrt(double a) {
    ...
}

veya

/**
 * Constructs a new String by converting the specified array of
 * bytes using the platform's default character encoding.
 */
public String(byte[] bytes) {
    ...
}

Aşağıdaki gibi önemsiz olsun ve set yöntemleri için yazma Javadoc gerekmez setFoo() derdi tüm Javadoc "setleri Foo" ise. Yöntem daha karmaşık bir şey yapıyorsa (bir kısıtlama uygulamak gibi veya önemli bir yan etkisi varsa), bunu belgelemeniz gerekir. "Foo" özelliğinin ne anlama geldiği açık değilse, bunu belgelemelisiniz.

Yazdığınız her yöntem, genel veya başka türlü Javadoc'tan yararlanacaktır. Genel yöntemler bir API'nin parçasıdır ve bu nedenle Javadoc gerektirir. Android Javadoc bir yorum yazmak için belirli bir stili zorlamaz, ancak yönergeleri takip etmelidir Javadoc Aracı için Doc yaz nasıl .

Kısa yöntemler yazın

Mümkün olduğunda, yöntemleri küçük ve odaklı tutun. Uzun yöntemlerin bazen uygun olduğunun farkındayız, bu nedenle yöntem uzunluğuna kesin bir sınır konmaz. Bir metot 40 satırı aşarsa, programın yapısına zarar vermeden bölünüp bölünemeyeceğini düşünün.

Standart yerlerde alanları tanımlayın

Alanları ya dosyanın üstünde ya da onları kullanan yöntemlerden hemen önce tanımlayın.

Değişken kapsamını sınırla

Yerel değişkenlerin kapsamını minimumda tutun. Bu, kodunuzun okunabilirliğini ve sürdürülebilirliğini artırır ve hata olasılığını azaltır. Her değişkeni, değişkenin tüm kullanımlarını kapsayan en içteki blokta bildirin.

Yerel değişkenleri ilk kullanıldıkları noktada bildirin. Neredeyse her yerel değişken bildirimi bir başlatıcı içermelidir. Henüz bir değişkeni mantıklı bir şekilde başlatmak için yeterli bilgiye sahip değilseniz, bunu yapana kadar bildirimi erteleyin.

Bunun istisnası, try-catch ifadeleridir. Bir değişken, denetlenen bir istisna oluşturan bir yöntemin dönüş değeriyle başlatılırsa, bir try bloğu içinde başlatılmalıdır. Değerin try bloğunun dışında kullanılması gerekiyorsa, henüz mantıklı bir şekilde başlatılamadığı try bloğundan önce bildirilmelidir:

// Instantiate class cl, which represents some sort of Set

Set s = null;
try {
    s = (Set) cl.newInstance();
} catch(IllegalAccessException e) {
    throw new IllegalArgumentException(cl + " not accessible");
} catch(InstantiationException e) {
    throw new IllegalArgumentException(cl + " not instantiable");
}

// Exercise the set
s.addAll(Arrays.asList(args));

Ancak, try-catch bloğunu bir yönteme dahil ederek bu durumdan kaçınabilirsiniz:

Set createSet(Class cl) {
    // Instantiate class cl, which represents some sort of Set
    try {
        return (Set) cl.newInstance();
    } catch(IllegalAccessException e) {
        throw new IllegalArgumentException(cl + " not accessible");
    } catch(InstantiationException e) {
        throw new IllegalArgumentException(cl + " not instantiable");
    }
}

...

// Exercise the set
Set s = createSet(cl);
s.addAll(Arrays.asList(args));

Aksini yapmak için zorlayıcı bir neden olmadıkça, for deyiminin kendisinde döngü değişkenlerini bildirin:

for (int i = 0; i < n; i++) {
    doSomething(i);
}

ve

for (Iterator i = c.iterator(); i.hasNext(); ) {
    doSomethingElse(i.next());
}

İthalat beyanlarını sipariş edin

İthalat ifadelerinin sıralaması şu şekildedir:

  1. Android ithalatı
  2. Üçüncü taraflardan İthalat ( com , junit , net , org )
  3. java ve javax

IDE ayarlarıyla tam olarak eşleşmesi için içe aktarmalar şu şekilde olmalıdır:

  • Her gruplama içinde, büyük harfler küçük harflerden önce olacak şekilde alfabetik (örneğin, a'dan önce Z)
  • Her ana gruplandırma arasında boş bir çizgi ile ayrılmış ( android , com , junit , net , org , java , javax )

Başlangıçta, siparişte herhangi bir stil gereksinimi yoktu, yani IDE'ler ya her zaman sıralamayı değiştiriyordu ya da IDE geliştiricilerinin otomatik içe aktarma yönetimi özelliklerini devre dışı bırakmaları ve içe aktarmaları manuel olarak sürdürmeleri gerekiyordu. Bu kötü kabul edildi. Java stili sorulduğunda, tercih edilen stiller çılgınca değişiyordu ve Android'e basitçe "bir sipariş seçip tutarlı olması" gerekti. Bu yüzden bir stil seçtik, stil kılavuzunu güncelledik ve IDE'lerin buna uymasını sağladık. IDE kullanıcıları kod üzerinde çalışırken, tüm paketlerdeki içe aktarmaların ekstra mühendislik çabası olmadan bu modelle eşleşmesini bekliyoruz.

Bu stili şu şekilde seçtik:

  • İnsanlar ilk bakmak istediğiniz ithalatı üst (en olma eğilimi android ).
  • İnsanlar en bakmak istiyorum ithalatı altta (en olma eğilimi java ).
  • İnsanlar üslubu kolayca takip edebilirler.
  • IDE'ler stili takip edebilir.

Statik ithalatları, normal ithalatlarla aynı şekilde sipariş edilen diğer tüm ithalatların üzerine koyun.

Girinti için boşluk kullanın

Bloklar için dört (4) boşluk girintisi kullanırız ve asla sekmeler kullanırız. Şüphe duyduğunuzda, çevreleyen kodla tutarlı olun.

İşlev çağrıları ve atamalar dahil olmak üzere satır sarma için sekiz (8) boşluk girintisi kullanırız.

Tavsiye edilen

Instrument i =
        someLongExpression(that, wouldNotFit, on, one, line);

Tavsiye edilmez

Instrument i =
    someLongExpression(that, wouldNotFit, on, one, line);

Alan adlandırma kurallarını takip edin

  • Sigara kamu, statik olmayan alan adları ile başlayan m .
  • Statik alan adları ile başlayan s .
  • Diğer alanlar küçük harfle başlar.
  • Kamu statik nihai alanlar (sabitler) olan ALL_CAPS_WITH_UNDERSCORES .

Örneğin:

public class MyClass {
    public static final int SOME_CONSTANT = 42;
    public int publicField;
    private static MyClass sSingleton;
    int mPackagePrivate;
    private int mPrivate;
    protected int mProtected;
}

Standart ayraç stilini kullanın

Parantezleri kendi satırlarına değil, önlerindeki kodla aynı satıra koyun:

class MyClass {
    int func() {
        if (something) {
            // ...
        } else if (somethingElse) {
            // ...
        } else {
            // ...
        }
    }
}

Koşullu ifadeler için parantezlere ihtiyacımız var. İstisna: Tüm koşul (koşul ve gövde) bir satıra sığıyorsa, hepsini bir satıra koyabilirsiniz (ancak zorunlu değilsiniz). Örneğin, bu kabul edilebilir:

if (condition) {
    body();
}

ve bu kabul edilebilir:

if (condition) body();

ama bu kabul edilemez:

if (condition)
    body();  // bad!

Çizgi uzunluğunu sınırla

Kodunuzdaki her metin satırı en fazla 100 karakter uzunluğunda olmalıdır. Çok tartışma bu kuralı çevrili olmasına rağmen, karar 100 karakter aşağıdaki istisnalar dışında maksimum olduğu kalır:

  • Bir yorum satırı, 100 karakterden uzun bir örnek komut veya hazır URL içeriyorsa, kesme ve yapıştırma kolaylığı için bu satır 100 karakterden uzun olabilir.
  • İçe aktarma satırları sınırı aşabilir çünkü insanlar bunları nadiren görür (bu ayrıca araç yazmayı da kolaylaştırır).

Standart Java ek açıklamalarını kullanın

Ek açıklamalar, aynı dil öğesi için diğer değiştiricilerden önce gelmelidir. (Örneğin, için basit işaretleyici açıklamalar @Override ) dili elemanı ile aynı hat üzerinde listelenebilir. Birden fazla açıklama veya parametreli açıklama varsa, bunları alfabetik sırayla her satırda bir tane olacak şekilde listeleyin.

Java'da önceden tanımlanmış üç ek açıklama için Android standart uygulamaları şunlardır:

  • Kullanım @Deprecated açıklamalı elemanın kullanılması önerilmez zaman ek açıklama. Eğer kullanırsanız @Deprecated ek açıklama, ayrıca bir olması gerekir @deprecated Javadoc etiketi ve alternatif bir uygulamayı isim olmalıdır. Buna ek olarak, unutmayın @Deprecated yöntem hala iş gerekiyordu. Bir sahiptir eski kod görürseniz @deprecated Javadoc etiketi ekleyin @Deprecated ek açıklama.
  • Kullanım @Override bir yöntem üst sınıftan beyanı veya uygulanmasını geçersiz kılar her ek açıklama. Kullanmak Örneğin, @inheritdocs bir sınıf (bir arabirimi değil) dan Javadoc etiketi ve türetmek, ayrıca Annotatesekmesindeki yöntemi ebeveyn sınıfının yöntemini geçersiz kılar gerektiğini söyledi.
  • Kullanım @SuppressWarnings sadece bir uyarı ortadan kaldırmak imkansız şartlar altında ek açıklama. Bir uyarı bu "imkansız ortadan kaldırmak için" testini geçerse, @SuppressWarnings açıklama bütün uyarılar kodunda gerçek sorunları yansıtmasını sağlamak için, kullanılmalıdır.

    Bir zaman @SuppressWarnings şerhi aranmaz, bu bir önek almış olmalıdır TODO koşulunu "ortadan kaldırmak imkansız" açıklıyor comment. Bu normalde, garip bir arayüze sahip rahatsız edici bir sınıfı tanımlar. Örneğin:

    // TODO: The third-party class com.third.useful.Utility.rotate() needs generics
    @SuppressWarnings("generic-cast")
    List<String> blix = Utility.rotate(blax);
    

    Bir zaman @SuppressWarnings açıklama gereklidir, açıklama geçerli yazılım elemanları izole için kodu yeniden.

Kısaltmaları kelime olarak ele alın

İsimleri daha okunaklı kılmak için değişkenleri, yöntemleri ve sınıfları adlandırırken kısaltmaları ve kısaltmaları kelimeler olarak ele alın:

İyi Kötü
XmlHttpTalebi XMLHTTPTalebi
getCustomerId getCustomerID
sınıf Html sınıf HTML'si
dize url'si Dize URL'si
uzun kimlik uzun kimlik

Hem JDK hem de Android kod tabanları, kısaltmalar konusunda tutarsız olduğundan, çevreleyen kodla tutarlı olmak neredeyse imkansızdır. Bu nedenle, kısaltmalara her zaman kelimeler gibi davranın.

YAPILACAKLAR yorumlarını kullanın

Kullanım TODO geçicidir kodu, kısa vadeli bir çözüm, ya da iyi, yeterli uzunlukta ama mükemmel değil için yapılan yorumlar. Bu yorumlar dize içermelidir TODO Bir kolon ile tamamı büyük,:

// TODO: Remove this code after the UrlTable2 has been checked in.

ve

// TODO: Change this to use a flag instead of a constant.

Senin Eğer TODO formunun olan "gelecekteki bir tarihte bir şeyler yapmak" emin ya belirli bir tarih ( "Fix Kasım 2005 tarafından") veya belirli bir olay (içerdiğini yapmak "Tüm üretim karıştırıcılar protokol V7 anlaşılması sonra bu kodu kaldırın." ).

Dikkatli bir şekilde oturum açın

Günlüğe kaydetme gerekli olmakla birlikte, performans üzerinde olumsuz bir etkisi vardır ve makul şekilde kısa tutulmazsa kullanışlılığını kaybeder. Günlüğe kaydetme olanakları, beş farklı günlüğe kaydetme düzeyi sağlar:

  • ERROR : Kullanım olduğunu oldu ölümcül bir şey, bir şey kullanıcı tarafından görülebilen sonuçlar doğuracaktır ve uygulamaları kaldırmayı, bazı verileri silme veri bölümleri silerek, ya da (daha kötüsü ya) tüm cihazı reflashing olmadan geri alınması mümkün değildir zaman. Bu seviye her zaman günlüğe kaydedilir. Bazı günlüğü haklı Sorunlar ERROR düzeyinde iyi adaylar bir istatistik toplama sunucusuna rapor edilecektir.
  • WARNING : Kullanım ciddi ve beklenmedik bir şey oldu, bir kullanıcı tarafından görülebilen sonuçlar doğurabilir ama bazı açık bir eylem gerçekleştirmeden bekleyen veya uygulama yeniden indirmek için tüm yol yeniden başlatarak arasında değişen veri kaybı olmadan geri kazanılabilir olması muhtemeldir bir şey bir uygulamanın yeni bir sürümü veya cihazın yeniden başlatılması. Bu seviye her zaman günlüğe kaydedilir. En giriş haklı Sorunlar WARNING düzeyinde de bir istatistik toplama sunucusuna raporlanması için düşünülebilir.
  • INFORMATIVE : Kullanım olsa mutlaka bir hata değildir, bir şeyin ilginç bir durum yaygın etkiye sahip olma olasılığı olduğunu tespit edildiğinde olduğunu, olanları nota. Böyle bir koşul, yalnızca o etki alanındaki en yetkili olduğuna inanan bir modül tarafından günlüğe kaydedilmelidir (yetkili olmayan bileşenler tarafından yinelenen günlüğe kaydetmeyi önlemek için). Bu seviye her zaman günlüğe kaydedilir.
  • DEBUG : araştırmak ve hata ayıklama beklenmedik davranışlar alakalı olabilir cihazda neler ileri nota kullanın. Yalnızca bileşeninizde neler olup bittiği hakkında yeterli bilgi toplamak için gerekenleri günlüğe kaydedin. Hata ayıklama günlükleriniz günlüğe hakimse, ayrıntılı günlük kullanmalısınız.

    Bu seviye bile sürüm yapılarında üzerine kaydedilir ve bir çevrili olması gereklidir if (LOCAL_LOG) ya if LOCAL_LOGD) blok, LOCAL_LOG[D] sınıf veya alt bileşen tanımlanmıştır, bu yüzden bu tür tüm günlüğü devre dışı bırakmak için bir olasılık var olduğunu . Bu nedenle, herhangi bir aktif mantık olmalıdır if (LOCAL_LOG) blok. Günlüğü için tüm dize binası da içine yerleştirilmesi gerekir if (LOCAL_LOG) bloğun. O yeri dışında almaya bina dize neden olacak eğer bir yöntem çağrısı içine günlüğü çağrıyı dışarı planı ayrı etmeyin if (LOCAL_LOG) bloğun.

    Hala diyor bazı kod var if (localLOGV) . Adı standart olmasa da, bu da kabul edilebilir olarak kabul edilir.

  • VERBOSE : diğer her şey için kullanın. Ayıklama oluşturur ve bir çevrili olmalıdır üzerindeki bu seviye sadece kaydedilir if (LOCAL_LOGV) varsayılan olarak dışarı derlenmiş olabilir böylece bloğun (veya eşdeğeri). Salma içinde görünecek inşa eder ve ihtiyaçlar Herhangi dize bina dışında çıkartılır if (LOCAL_LOGV) bloğun.

Notlar

  • En dışındaki belirli bir modül, içinde VERBOSE seviyesinde bir hata sadece bir kez mümkünse bildirilmelidir. Bir modül içindeki tek bir işlev çağrıları zincirinde, yalnızca en içteki işlev hatayı döndürmeli ve aynı modüldeki arayanlar, yalnızca sorunun yalıtılmasına önemli ölçüde yardımcı oluyorsa, bir miktar günlük eklemelidir.
  • En dışındaki modüllerin bir zincir, içinde VERBOSE daha düşük seviyeli modül üst seviye bir modülünden gelen geçersiz veri algıladığında düzeyde, alt düzey modülü sadece bu durumu log gerektiğini DEBUG günlüğüne ve günlük sağlar yalnızca arayan kişi için başka türlü mevcut olmayan bilgiler. Özellikle, bir istisnanın oluşturulduğu (istisna tüm ilgili bilgileri içermelidir) veya günlüğe kaydedilen tek bilginin bir hata kodunda bulunduğu durumları günlüğe kaydetmeye gerek yoktur. Bu düzgün daha yüksek giriş başlatmaması gereken çerçeve tarafından işlenir üçüncü taraf uygulamaların neden çerçeve ve uygulamalar ve koşullar arasındaki etkileşim özellikle önemlidir DEBUG düzeyinde. En günlüğü tetiklemesi gereken tek durumlar INFORMATIVE bir modül veya uygulama kendi seviyesinde bir hata algıladığında veya bir alt seviyeden gelirken daha yüksek seviyede ya da olduğunu.
  • Normalde bazı günlüğe kaydetmeyi haklı çıkaracak bir koşulun birçok kez meydana gelmesi muhtemel olduğunda, günlüklerin aynı (veya çok benzer) bilgilerin birçok yinelenen kopyasıyla taşmasını önlemek için bazı hız sınırlama mekanizmaları uygulamak iyi bir fikir olabilir.
  • Ağ bağlantısı kayıpları yaygın olarak kabul edilir ve tamamen beklenir ve nedensiz bir şekilde günlüğe kaydedilmemelidir. Bir uygulama içinde sonuçları vardır ağ bağlantısı zararına kaydedilir gereken DEBUG veya VERBOSE (sonuçlar için yeterince ciddi ve beklenmeyen kadar bir yayın oluşturma kaydedilebilir için olup olmadığına bağlı olarak) seviyesi.
  • Üçüncü taraf uygulamalar tarafından veya adına erişilebilen bir dosya sisteminde tam bir dosya sistemine sahip olmak, BİLGİLENDİRME'den daha yüksek bir düzeyde günlüğe kaydedilmemelidir.
  • (Paylaşılan herhangi depolamada dosyaya veya bir ağ bağlantısı üzerinden gelen veriler dahil) herhangi bir güvenilmeyen bir kaynaktan gelen geçersiz veri beklenen sayılır ve daha yüksek bir seviyede herhangi günlüğünü algılanmaması gerekir DEBUG bu tespit ne zaman geçersiz olduğu (ve o zaman bile günlüğü mümkün olduğunca sınırlı olmalıdır).
  • Üzerinde kullanıldığında String nesneler, + operatörü örtük bir oluşturur StringBuilder varsayılan arabellek boyutu (16 karakter) ve potansiyel olarak diğer geçici ile örneğini String nesneleri. Yani açıkça oluşturarak StringBuilder nesneleri varsayılan güvenerek daha pahalı değildir + operatörü (ve çok daha verimli olabilir). Çağıran kod unutmayın Log.v() derlenmiş ve serbest bırakılması üzerinde yürütülen günlükleri okuma varlık olmasalar bile, dizeleri bina dahil inşa edilir.
  • Başkaları tarafından okunması ve sürüm yapılarında bulunması gereken herhangi bir günlük kaydı, şifreli olmadan özlü olmalı ve anlaşılabilir olmalıdır. Bu tüm günlük toplantı için geçerlidir DEBUG düzeyinde.
  • Mümkün olduğunda, tek bir satırda oturum açmaya devam edin. 80 veya 100 karaktere kadar satır uzunlukları kabul edilebilir. Mümkünse yaklaşık 130 veya 160 karakterden (etiketin uzunluğu dahil) daha uzun olan uzunluklardan kaçının.
  • Raporlar başarılar giriş ise daha yüksek seviyelerde kullanmak asla VERBOSE .
  • Çoğaltmak zor bir sorunu teşhis etmek için geçici günlük kullanıyorsanız, başında tutmak DEBUG veya VERBOSE seviyesi ve içine alın derleme sırasında işlevsiz kılınması için izin bloklar halinde.
  • Günlük yoluyla güvenlik sızıntılarına karşı dikkatli olun. Özel bilgileri günlüğe kaydetmekten kaçının. Özellikle, korunan içerikle ilgili bilgileri günlüğe kaydetmekten kaçının. Bu, özel bilgilerin veya korunan içeriğin ne olup olmayacağını önceden bilmek kolay olmadığından, çerçeve kodu yazarken özellikle önemlidir.
  • Asla kullanmayın System.out.println() (veya printf() yerli kodu için). System.out ve System.err olsun yönlendirilen için /dev/null , yazdırma ifadeleri görünür etkilere sahip bu yüzden. Ancak, bu çağrılar için gerçekleşen tüm dize oluşturma işlemi yine de yürütülür.
  • Günlüğe kaydetmenin altın kuralı, günlüklerinizin diğer günlükleri arabellekten gereksiz yere itmemesidir, tıpkı diğerlerinin sizinkileri dışarı itmemesi gibi.

Javatest stil kuralları

Test yöntemi adlandırma kurallarını takip edin ve test edileni test edilen özel durumdan ayırmak için bir alt çizgi kullanın. Bu stil, hangi vakaların test edildiğini görmeyi kolaylaştırır. Örneğin:

testMethod_specificCase1 testMethod_specificCase2

void testIsDistinguishable_protanopia() {
    ColorMatcher colorMatcher = new ColorMatcher(PROTANOPIA)
    assertFalse(colorMatcher.isDistinguishable(Color.RED, Color.BLACK))
    assertTrue(colorMatcher.isDistinguishable(Color.X, Color.Y))
}