Styl kodu Java AOSP dla współtwórców

Style kodu na tej stronie są rygorystycznymi regułami dotyczącymi udziału kodu Java w Android Open Source Project (AOSP). Wkład w rozwój platformy Androida , które nie są zgodne z tymi zasadami, zasadniczo nie są akceptowane. Śr że nie cały istniejący kod jest zgodny z tymi regułami, nowego kodu. Patrz: Kodowanie z szacunkiem zawiera przykłady terminologii, których należy używać i których należy unikać w ekosystemie promującym integrację społeczną.

Zadbaj o spójność

ZACHOWAJ Spójność. Jeśli edytujesz kod, na obejrzenie otaczającego go kodu i określenie jego stylu. Jeśli kod używa spacji wokół klauzul if, warto też używać spacji. Jeśli kod komentarze są otoczone małymi gwiazdkami, spraw, aby były wokół nich również małe pudełka gwiazd.

Celem wytycznych dotyczących stylu jest powszechne używanie w taki sposób, by czytelnicy mogli skupić się na tym, co mówisz, a nie na jak to mówisz. Przedstawiamy tu globalne reguły stylu, aby pokazać, ale ważny jest także styl lokalny. Jeśli dodany przez Ciebie kod wygląda zupełnie inaczej niż otaczający go kod, czytelnicy nie rozumieją rytmu, gdy czytają. Spróbuj tego uniknąć.

Reguły języka Java

Android przestrzega standardowych konwencji kodowania w Javie i ma dodatkowe reguły. opisane poniżej.

Nie ignoruj wyjątków

Może Cię kusić, aby napisać kod ignorujący wyjątek, na przykład:

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

Nie wolno tak postępować. Może się wydawać, że Twój kod nigdy go nie napotka lub że nie trzeba się tym zajmować, ignorując ten typ tworzy w Twoim kodzie miny, tak aby ktoś inny które wywołają jakiś dzień. Każdy wyjątek w kodzie musisz uwzględnić w tagu w sposób zgodny z zasadami; sposób postępowania może się różnić w zależności od konkretnego przypadku.

„Gdy ktoś używa pustej klauzuli „catch”, powinien wywoływać przerażający tekst uczucie. Z pewnością zdarzają się sytuacje, w których ale przynajmniej dobrze przemyśleć. W Javie nie można uniknąć strachu”. – James Gosling

Dopuszczalne alternatywne rozwiązania (wg preferencji) to:

• Zgłaszaj wyjątek do osoby wywołującej swoją metodę.

    void setServerPort(String value) throws NumberFormatException {
        serverPort = Integer.parseInt(value);
    }
  

• Dodaj nowy wyjątek odpowiedni do Twojego poziomu abstrakcji.

    void setServerPort(String value) throws ConfigurationException {
      try {
          serverPort = Integer.parseInt(value);
      } catch (NumberFormatException e) {
          throw new ConfigurationException("Port " + value + " is not valid.");
      }
    }
  

• Napraw błąd i zastąp odpowiednią wartość w kolumnie Blok catch {}.

    /** 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
      }
    }
  

• Wykryj wyjątek i zgłoś nowe wystąpienie RuntimeException. To niebezpieczne. Rób to tylko wtedy, gdy masz pewność, że jeśli wystąpi błąd, należy zrobić awarię.

    /** 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);
      }
    }
  

• W ostateczności, jeśli masz pewność, że zignorowanie wyjątku jest odpowiednie, możesz je zignorować, ale przy okazji uzasadnić też to dobry powód.

  /** 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.
      }
  }
  

Nie uwzględniaj ogólnych wyjątków

Może być kuszące, żeby być leniwym, wyłapując wyjątki i podejmować kroki np.:

  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!
  }

Nie wolno tak postępować. Prawie we wszystkich przypadkach chwytywanie ogólnych informacji jest niewłaściwe Exception lub Throwable (najlepiej nie Throwable ponieważ zawiera ona Error wyjątków). Jest niebezpieczny, ponieważ oznacza, że wyjątki nigdy się nie spodziewasz (łącznie z wyjątkami czasu działania, takimi jak ClassCastException) nie musisz przetwarzać błędów na poziomie aplikacji. Ukrywa porażkę, obsługi właściwości kodu, czyli gdy ktoś doda nowy typ w wybieranym kodzie, kompilator nie wskaże musisz w inny sposób radzić sobie z tym błędem. W większości przypadków nie należy traktować różnych typów wyjątków w ten sam sposób.

Rzadkim wyjątkiem od tej reguły jest kod testowy i kod najwyższego poziomu, w którym chcesz wychwytywać wszelkiego rodzaju błędy (aby zapobiegać ich wyświetlaniu), w interfejsie użytkownika lub do dalszego działania zadania wsadowego). W takich przypadkach możesz wykryć ogólny Exception (lub Throwable) i odpowiednio napraw błąd. Dobrze się jednak zastanów, zanim to zrobisz, i dodawaj komentarze dlaczego jest to bezpieczne w tym kontekście.

Alternatywy dla ogólnych wyjątków:

• Przechwytuj każdy wyjątek oddzielnie w ramach bloku wielofunkcyjnego, na przykład:

  try {
      ...
  } catch (ClassNotFoundException | NoSuchMethodException e) {
      ...
  }

• Refaktoryzacja kodu pozwala na bardziej precyzyjną obsługę błędów przy użyciu wiele bloków trygonometrycznych. Podziel zamówienie reklamowe od analizy i obsługuj błędy z osobna.
• Zgłoś wyjątek jeszcze raz. Często nie trzeba wychwytywać na tym poziomie, po prostu pozwól, aby metoda go zgłaszała.

Pamiętaj, że wyjątki to Twoi sprzymierzeńcy. Gdy kompilator narzeka, że jeśli nie zrobię wyjątku, nie śmiej się. Uśmiech! Kompilator właśnie to zrobił ułatwia wykrywanie problemów z czasem działania w kodzie.

Nie używaj finalizatorów

Finaliści to sposób na wykonanie fragmentu kodu, gdy obiekt na śmieci. Finalizer może być jednak przydatny do czyszczenia (zwłaszcza w przypadku zasobów zewnętrznych), nie ma gwarancji, kiedy a finalizator zostanie wywołany (a nawet że zostanie w ogóle wywołany).

Android nie korzysta z finalizatorów. W większości przypadków możesz użyć atrybutu do obsługi wyjątków. Jeśli potrzebujesz finalizatora, zdefiniować metodę close() (lub podobną) i dokument, kiedy to musi zostać wywołana (patrz InputStream). W tym przypadku jest odpowiedni, ale nie jest wymagany do wydrukowania krótkiego komunikatu dziennika finalizer, o ile nie ma zapełniać logów.

Importy w pełni kwalifikujące się

Kiedy chcesz użyć klasy Bar z pakietu foo, są dostępne dwie możliwe sposoby importu:

• import foo.*;

  Potencjalnie zmniejsza liczbę instrukcji importowych.

• import foo.Bar;

  Jasno widać, które klasy są używane, a kod jest lepszy. czytelna dla opiekunów.

Użyj import foo.Bar; do zaimportowania całego kodu Androida. An dla standardowych bibliotek Java (java.util.*, java.io.* itp.) i kod testu jednostkowego (junit.framework.*).

Reguły biblioteki Java

W przypadku Androida obowiązują określone konwencje dotyczące używania bibliotek i narzędzi Java. W W niektórych przypadkach konwencja uległa zmianie w istotny sposób, a starszy kod może używać wycofanego wzorca lub biblioteki. Podczas pracy z takim kodem można kontynuować istniejący styl. Podczas tworzenia nowych komponentów jednak nigdy nie używaj wycofanych bibliotek.

Reguły stylu Java

Używaj standardowych komentarzy w języku Javadoc

Każdy plik powinien zawierać u góry oświadczenie o prawach autorskich, po którym następuje ciąg instrukcje package i import (każdy blok oddzielony pustym wierszem) oraz na końcu klasy lub interfejsu. W komentarzach Javadoc opisują działanie klasy lub interfejsu.

/*
 * Copyright yyyy 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 {
    ...
}

Każda napisana przez Ciebie klasa i nietrudna metoda publiczna muszą zawierać komentarz w języku Javadoc zawierający co najmniej jedno zdanie opisujące treść zajęć, lub metody ich stosowania. To zdanie powinno zaczynać się od osoby trzeciej czasownik opisowy.

Przykłady

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

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

lub

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

Nie trzeba pisać w języku Javadoc, aby stosować proste metody get i set, takie jak setFoo(), jeśli w pliku Javadoc znajdziesz wyłącznie hasło „sets Foo”. Jeśli metoda wykonuje coś bardziej złożonego (na przykład egzekwuje ona ograniczenie lub ma istotny efekt uboczny), musisz to udokumentować. Jeśli nie jest oczywiste, co to jest właściwość „Foo”, co oznacza, że należy to udokumentować.

Każda napisana przez Ciebie metoda (publiczna lub inna) będzie przydatna na Javadoc. Metody publiczne są częścią interfejsu API i dlatego wymagają języka Javadoc. Android, nie wymusza określonego stylu pisania w języku Javadoc ale zalecamy wykonanie czynności opisanych w artykule Jak pisać komentarze do dokumentów dla narzędzia Javadoc.

Napisz krótkie metody

Jeśli to możliwe, staraj się, by metody były małe i precyzyjne. Wiemy, że czas są czasami odpowiednie, więc nie ma sztywnych ograniczeń długości. Jeśli metoda ma ponad 40 wierszy, zastanów się, czy może nie zostanie zniszczona bez szkody dla struktury programu.

Zdefiniuj pola w miejscach standardowych

Zdefiniuj pola na początku pliku lub bezpośrednio przed które z nich korzystają.

Ogranicz zakres zmiennej

Ogranicz zakres zmiennych lokalnych do minimum. Ten poprawia czytelność i łatwość obsługi kodu oraz zmniejsza prawdopodobieństwo błędu. Zadeklaruj każdą zmienną w najbardziej wewnętrznej który obejmuje wszystkie zastosowania zmiennej.

Zmienne lokalne należy deklarować w miejscu, w którym są po raz pierwszy używane. Prawie każda deklaracja zmiennych lokalnych powinna zawierać inicjator. Jeśli nie masz jeszcze wystarczającej ilości informacji, aby zainicjować zmienną odłóż tę deklarację do czasu, gdy to zrobisz.

Wyjątkiem są instrukcje try-catch. Jeśli zmienna jest zainicjowana przy użyciu parametru wartość zwrotna metody, która zgłasza sprawdzony wyjątek, musi być zainicjowano w bloku try. Jeśli wartość musi być używana poza ciągiem try block, to musi być zadeklarowany przed blokiem try, gdzie nie można jeszcze rozsądnie zainicjować:

// 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));

Można jednak nawet tego uniknąć, umieszczając kodowanie try-catch :

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));

Deklaruj zmienne pętli for w instrukcji for, chyba że jest przekonujący powód, by zrobić inaczej:

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

i

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

Wyciągi dotyczące importu zamówienia

Kolejność wyciągów dotyczących importu:

1. Importowane dane z Androida
2. Importy od innych firm (com, junit, net i org)
3. java i javax

Aby dokładnie zgadzały się z ustawieniami IDE, importy powinny wyglądać tak:

• Alfabetycznie w każdej grupie, przed małymi literami w postaci dużych liter wielkość liter (np. Z przed a)
• Oddzielone pustym wierszem między każdą główną grupą (android, com, junit, net, org, java, javax).

Początkowo nie było wymagań dotyczących stylu, co oznacza, że IDE albo ciągle zmieniali kolejność, albo programiści IDE musieli wyłącz funkcje automatycznego zarządzania importem i ręcznie importowanie danych. Uznano to za niewłaściwe. W odpowiedzi na pytanie w stylu Java różne style różnią się od siebie aż do Androida. po prostu „wybierz kolejność i zachowaj spójność”. Wybraliśmy styl, zaktualizowaliśmy przewodnik po stylach i zadbał o zgodność IDE. Przewidujemy, że Użytkownicy IDE pracują nad kodem, pasują do tego importy we wszystkich pakietach bez dodatkowej pracy inżynierskiej.

Wybraliśmy ten styl, ponieważ:

• Importy, które użytkownicy chcą sprawdzić w pierwszej kolejności, znajdują się na początku (android).
• Importy, które użytkownicy chcą sprawdzić, znajdują się zwykle na dole (java).
• Użytkownicy mogą z łatwością nadążyć za stylem
• IDE mogą być zgodne z tym stylem.

Importy statyczne umieść nad wszystkimi pozostałymi importami, w kolejności takiej jak do zwykłych obciążeń.

Użyj spacji do wcięcia

W blokach stosujemy cztery (4) wcięcia spacji. W razie wątpliwości zachować spójność z kodem otoczenia.

W przypadku zawijania wierszy korzystamy z ośmiu (8) wcięć spacji, w tym wywołań funkcji. i projekty.

Zalecane

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

Niezalecane

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

Przestrzegaj konwencji nazewnictwa pól

• Niepubliczne, niestatyczne nazwy pól zaczynają się od m.
• Statyczne nazwy pól zaczynają się od s.
• Inne pola zaczynają się od małej litery.
• Statyczne pola końcowe (stałe, ściśle stałe) to ALL_CAPS_WITH_UNDERSCORES.

Na przykład:

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;
}

Użyj standardowego stylu nawiasu klamrowego

Umieść nawiasy klamrowe w tym samym wierszu co kod poprzedzający je, a nie w osobnym wierszu:

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

W przypadku instrukcji warunkowych wymagane jest stosowanie nawiasów klamrowych. Wyjątek: jeśli cały warunkowy (stan i ciało) mieszczą się w jednym wierszu, mogą (ale nie ma obowiązku) umieścić wszystko w jednym wierszu. Na przykład to jest akceptowalna:

if (condition) {
    body();
}

i akceptowalna jest:

if (condition) body();

ale nie jest to dozwolone:

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

Ogranicz długość wiersza

Każdy wiersz tekstu w kodzie może mieć maksymalnie 100 znaków. Zasada ta została omówiona dość często, ale decyzja pozostaje że maksymalna długość to 100 znaków przy wyjątki:

• Jeśli wiersz komentarza zawiera przykładowe polecenie lub dłuższy URL 100 znaków, ten wiersz może być dłuższy niż 100 znaków w przypadku możliwość łatwego wycinania i wklejania.
• Linie importu mogą przekraczać limit, ponieważ ludzie rzadko je widzą (upraszcza to również pisanie w narzędziach).

Użyj standardowych adnotacji w Javie

Adnotacje powinny poprzedzać inne modyfikatory tego samego języka . Proste adnotacje ze znacznikami (np. @Override) można umieścić na z elementem language. Jeśli istnieje wiele adnotacji, lub adnotacjach z parametrami, należy wymień je pojedynczo w wierszu w porządku alfabetycznym.

Standardowe metody Androida dotyczące trzech wstępnie zdefiniowanych adnotacji w Javie to:

• Używanie adnotacji @Deprecated za każdym razem, gdy odradzamy użycie takiego elementu. Jeśli używasz adnotacji @Deprecated, musisz też mieć @deprecated tagu Javadoc i powinien on nazywać alternatywną implementację. Ponadto pamiętaj, że metoda @Deprecated nadal powinna działać. Jeśli widzisz stary kod, który zawiera tag Javadoc @deprecated, dodaj tag Adnotacja @Deprecated.
• Używaj adnotacji @Override, gdy zastępuje deklarację lub implementację z klasa nadrzędna. Jeśli np. używasz tagu Javadoc @inheritdocs, wywodzą się z klasy (nie interfejsu), musisz również dodać adnotację, że zastępuje metodę klasy nadrzędnej.
• Używanie adnotacji @SuppressWarnings tylko w sytuacjach, gdy nie da się dokonać mogą wyeliminować ostrzeżenie. Jeśli ostrzeżenie minie ten proces, wyeliminować” test, adnotacja @SuppressWarnings musi być używane, aby upewnić się, że wszystkie ostrzeżenia odzwierciedlają rzeczywiste problemy w kodzie.

  Jeśli adnotacja @SuppressWarnings jest potrzebna, musi zostać poprzedzony komentarzem TODO wyjaśniającym, że „nie można wyeliminować” . Zwykle identyfikuje to klasę naruszającą zasady z niezręcznym interfejsem. Na przykład:

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

  Gdy wymagana jest adnotacja @SuppressWarnings, zrefaktoryzuj kod aby wyodrębnić elementy oprogramowania, w których adnotacja ma zastosowanie.

Traktuj skróty jako słowa

Traktuj akronimy i skróty jako słowa w nazywaniu zmiennych, metod, i klas, aby nazwy były bardziej czytelne:

Stan dobry	Zła
XmlHttpRequest	XMLHTTPRequest
getCustomerId.	getCustomerID
klasa HTML	kod HTML zajęć
URL ciągu tekstowego	Adres URL ciągu znaków
długi identyfikator	długi identyfikator

Ponieważ baza kodu JDK i Androida są niespójne akronimów, zapewnienie spójności z otaczającego kod. Dlatego zawsze traktuj akronimy jako słowa.

Używanie komentarzy typu TODO

Użyj komentarzy TODO w przypadku kodu, który jest tymczasowy lub krótkoterminowy. wystarczająco dobry, ale nie idealny. Komentarze te powinny zawierać ciąg TODO we wszystkich wielkie litery z dwukropkiem:

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

i

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

Jeśli TODO ma postać „W przyszłości zrób coś” upewnić się, Podanie konkretnej daty („Popraw do listopada 2005 r.”) lub określone zdarzenie („Usuń ten kod, gdy wszystkie miksery produkcyjne rozumieją protokół V7”).

Loguj z umiarem

Choć logowanie jest niezbędne, ma negatywny wpływ na wydajności i traci przydatność, jeśli nie zostanie rozsądnie zachowana. zwięźle. Wycinki drzew oferują pięć różnych poziomów zapisu:

• ERROR: używaj, gdy zdarzy się coś krytycznego, czyli będzie się wiązało z konsekwencjami widocznymi dla użytkownika i nie będzie można go odzyskać bez usuwania części danych, odinstalowania aplikacji czyścić partycje danych albo ponownie zainstalować całe urządzenie (lub co gorsza). Ten poziom jest zawsze rejestrowany. Problemy, które uzasadniają logowanie Poziom ERROR to dobry kandydat, który warto zgłosić serwera do gromadzenia statystyk.
• WARNING: użyj w przypadku poważnych i nieoczekiwanych działań czyli coś, co będzie miało konsekwencje widoczne dla użytkowników, może być możliwe do odzyskania bez utraty danych dzięki wyraźne działanie, np. oczekiwanie lub ponowne uruchomienie aplikacji; ponowne pobranie nowej wersji aplikacji lub zrestartowanie urządzenia. Ten poziom jest zawsze rejestrowany. Problemy, które uzasadniają logowanie na poziomie WARNING może być również brana pod uwagę w kontekście raportowania serwera do gromadzenia statystyk.
• INFORMATIVE: użyj, aby zanotować coś interesującego czyli gdy zostanie wykryta sytuacja, która może ma szeroki wpływ, choć nie musi to być błąd. Taki powinien być rejestrowany tylko przez moduł, który uważa, że jest to najbardziej rzetelne w tej domenie (aby uniknąć powielania logowania przy użyciu niemiarodajnych komponentów). Ten poziom jest zawsze rejestrowany.
• DEBUG: służy do sprawdzania, co dzieje się na urządzeń, które mogą okazać się przydatne do badania i debugowania nieoczekiwanych wyników zachowań. Zapisuj tylko to, co jest potrzebne, aby zebrać wystarczającą ilość danych o tym, co dzieje się z komponentem. Jeśli dane debugowania gdy logi dominują, użyj opcji Szczegółowa logowanie.

  Ten poziom jest rejestrowany nawet w przypadku kompilacji wersji i jest wymagany jest otoczony blokiem if (LOCAL_LOG) lub if LOCAL_LOGD), gdzie LOCAL_LOG[D] jest zdefiniowany w swojej klasie lub podkomponencie, tak aby możliwe było wyłączenia takiego rejestrowania. Dlatego nie może występować żadna logika w bloku if (LOCAL_LOG). Budowanie struny należy też umieścić dziennik Blok if (LOCAL_LOG). Nie refaktoryzuj wywołania logowania do wywołania metody, jeśli spowoduje to budowania struny, które mają się odbywać poza Blok if (LOCAL_LOG).

  Nadal jest kod: if (localLOGV). Ten jest również uznawana za akceptowalną, ale nazwa jest niestandardowa.

• VERBOSE: używaj w pozostałych przypadkach. Ten poziom to tylko logowanych w kompilacji debugowania i powinien być otoczony if (LOCAL_LOGV) (lub odpowiednika), aby można było są domyślnie kompilowane. Fragmenty tekstu w budynku są usuwane i musi się pojawić w Blok if (LOCAL_LOGV).

Uwagi

• W danym module (innym niż na poziomie VERBOSE) występuje błąd w miarę możliwości należy zgłosić tylko raz. W ramach jednego łańcucha funkcji wewnętrznych, tylko najbardziej wewnętrzna funkcja powinna zwraca błąd, a elementy wywołujące w tym samym module powinny dodawać tylko zapisywanie danych, jeśli to znacznie pomaga w identyfikacji problemu.
• W łańcuchu modułów innego niż na poziomie VERBOSE, gdy moduł niższego poziomu wykrywa nieprawidłowe dane pochodzące z wyższego poziomu, moduł niższego poziomu powinien rejestrować tę sytuację tylko w DEBUG i tylko wtedy, gdy logowanie dostarcza informacji, które nie są w inny sposób dostępne dla rozmówcy. W szczególności nie trzeba sytuacje w logu, w których został zgłoszony wyjątek (wyjątek powinien zawierają wszystkie istotne informacje) lub gdy jedyne informacje jest zawarte w kodzie błędu. Jest to szczególnie ważne, są ważne w interakcji między platformą a aplikacjami, i warunków powodowanych przez aplikacje innych firm, które działają prawidłowo obsługiwane przez platformę nie powinny aktywować logowania większego niż Poziom DEBUG. Jedyne sytuacje, które powinny aktywować logowanie w miejscu, na poziomie INFORMATIVE lub wyższym, gdy moduł lub aplikacja wykryje, błąd na własnym poziomie lub pochodzący z niższego poziomu.
• Gdy warunek, który zwykle uzasadniałoby zachowywanie pewnych danych, jest prawdopodobny mogą pojawiać się wielokrotnie, warto więc wdrożyć pewne mechanizm ograniczania szybkości wczytywania, by zapobiec przepełnieniu logów powielonych kopii tych samych (lub bardzo podobnych) informacji.
• Utrata połączenia sieciowego jest uznawana za powszechną i w pełni nie powinny być rejestrowane bezzasadnie. Utrata sieci które mają konsekwencje w aplikacji, należy rejestrować DEBUG lub VERBOSE (w zależności od tego, konsekwencje są na tyle poważne i nieoczekiwane, że trzeba je zapisać kompilację).
• jeśli w systemie plików znajduje się pełny system plików, który jest dostępny dla wszystkich lub w tych usługach; aplikacji innych firm nie powinny być rejestrowane na poziomie wyższy niż INFORMATIVE.
• Nieprawidłowe dane pochodzące z niezaufanego źródła (w tym z plików pamięci współdzielonej lub danych przesyłanych przez sieć połączenia) jest uznawany za oczekiwany i nie powinien wywoływać żadnych logowanie na poziomie wyższym niż DEBUG, jeśli zostanie wykryte nieprawidłowe (nawet wtedy logowanie powinno być maksymalnie ograniczone).
• W przypadku stosowania do obiektów String operator + jest niejawnie tworzy instancję StringBuilder z domyślną wartością rozmiar bufora (16 znaków) i potencjalnie inne tymczasowe pole String obiektów. Bezpośrednie tworzenie obiektów StringBuilder nie jest więc niż w przypadku domyślnego operatora + (i może być bardzo bardziej efektywne). Pamiętaj, że kod, który nawiązuje połączenie telefoniczne Narzędzie Log.v() jest kompilowane i uruchamiane w kompilacjach do publikacji. w tym tworzenie ciągów tekstowych, nawet jeśli logi nie są odczytywane.
• wszelkie zapisy przeznaczone do odczytu przez inne osoby i dostępne w kompilacjach wersji powinny być zwięzłe i tajemnicze. i powinny być zrozumiałe. Obejmuje to wszystkie logowanie do poziomu DEBUG.
• Jeśli to możliwe, zapisuj dalej w jednym wierszu. Długość wierszy nie może przekraczać 80 lub 100 znaków jest akceptowalna. Nie powinna zawierać więcej niż około 130 lub 160 znaków. (łącznie z długością tagu) jeśli to możliwe.
• Jeśli logowanie zgłasza sukcesy, nie używaj go na wyższych poziomach niż VERBOSE.
• Jeśli używasz tymczasowego logowania do diagnozowania problemu, który trudno jest odtworzyć go na poziomie DEBUG lub VERBOSE i należy ją ująć w bloki, które umożliwiają wyłączenie czas kompilowania.
• Uważaj na wyciek informacji o zabezpieczeniach w dzienniku. Unikaj logowania prywatnego i informacjami o nich. W szczególności unikaj rejestrowania informacji o treści chronionej. Jest to szczególnie ważne, gdy w tworzeniu kodu platformy, ponieważ nie jest łatwo przewidzieć z góry, co i nie będą prywatnymi informacjami ani treściami chronionymi.
• Nigdy nie używaj zasady System.out.println() (lub printf() w przypadku kodu natywnego). System.out i System.err otrzymują przekierowano do /dev/null, więc wyciągi drukowane nie zawierają widoczne efekty. Jednak wszystkie etapy budowania struny takie połączenia są nadal wykonywane.
• Złotą zasadą rejestrowania jest to, że dzienniki niepotrzebnie wypychać inne logi z bufora, tak jak inne ale nie wypchnij swojego.

Reguły stylu języka Javatests

Przestrzegaj konwencji nazewnictwa metod testowych i użyj podkreślenia, aby rozdzielić bada się na podstawie konkretnego przypadku. Ten styl sprawia, łatwiej jest zobaczyć, które przypadki są aktualnie testowane. Na przykład:

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))
}