A Java kódolás bevált gyakorlatainak rövid összefoglalása

az Oracle, a Google, a Twitter és a Spring Framework kódolási szabványai alapján

Ennek a cikknek az a célja, hogy gyorsan összefoglalja Önt a tennivalókról, más szóval, nem részesíti előnyben és kerülje el olyan technológiai óriások, mint az Oracle, a Google, a Twitter és a Spring Framework kódolási szabványai alapján.

Lehet, hogy nem ért egyet az itt bemutatott bevált gyakorlatokkal, és ez teljesen rendben van, amíg létezik valamilyen kódolási szabvány.

Miért elsősorban a szabványok kódolása? Számos jó oka van annak, ha Ön Google-ként használja, és a következő ábrát hagyom neked

A kódolási szabványok dokumentuma hosszú és unalmas lehet. Ez a cikkcseresznye bit és darabokat vesz a Google, az Oracle, a Twitter és a Spring kódolási konvencióiból, és célja, hogy könnyen követhető és kevésbé unalmas gyakorlatokat biztosítson az Ön számára, hogy a kód könnyen olvasható és karbantartható legyen.

Szinte mindig csatlakozni fog a létező szoftverekkel dolgozó csapatokhoz, és nagyon nagy esély van arra, hogy a szerzők többsége elhagyta vagy átváltott különböző projektekre, és olyan kódrészekkel maradt benne, amelyek megkérdőjelezik az emberiséget.

Merüljünk el a különféle kódolási szabványok legjobb gyakorlataiba.

Java forrásfájl

A java forrásfájlok esetében az alábbiak tekinthetők legjobb gyakorlatnak:

  • A forrásfájl hossza kevesebb, mint 2000 sor sor
  • A forrásfájlt dokumentációs megjegyzés, csomag-nyilatkozat, majd osztály-megjegyzés követi, az import csoportosítva (statikus utolsó), osztály / interfész aláírással és így tovább, az alábbiak szerint
com.example.model csomag;
/ **
 * Végrehajtás-mentes perspektíva, amelyet a fejlesztőknek el kell olvasniuk
 * akiknek nem feltétlenül kell rendelkezniük a forráskóddal
 *
 * @author x, y, z
 * @date
 * @verzió
 * @szerzői jog
 *
 * /
import com.example.util.FileUtil;
/ *
 * Opcionális osztály-specifikus megjegyzés
 *
 * /
public class SomeClass {
  // Statikus változók a láthatóság szerint
  nyilvános statikus végleges egész szám PUBLIC_COUNT = 1;
  statikus végleges egész szám PROTECTED_COUNT = 1;
  privát statikus végleges egész szám PRIVATE_COUNT = 1;
  // Példányváltozók a láthatóság szerint
  nyilvános karakterlánc neve;
  Karakterlánc postalCode;
  privát karakterlánc cím;
  // Konstruktor és túlterhelt sorrendben
  nyilvános SomeClass () {}
  public SomeClass (karakterlánc neve) {
    this.name = név;
  }
  // Módszerek
  nyilvános karakterlánc doSomethingUseful () {
    vissza "Valami hasznos";
  }
  // getters, setter, equals, hashCode és toString a végén
}

elnevezése

Az osztály- és interfésznevek CamelCase, és ajánlott a teljes szó használata, és kerülje a rövidítéseket / rövidítéseket. Például a Raszter osztály vagy az ImageSprite osztály

  • Csomag - a com.deepspace nevét a com.deepSpace vagy a com.deep_space fölé nevezzük
  • A fájlnevek CamelCase és az .java-val végződnek, amely megegyezik az osztály nevével. Egy fájlonként egy nyilvános osztály található, és a fájlban minden egyes felső szintű osztály található
  • Módszer - a neveknek vegyesbetűsnek kell lenniük igékkel, minden belső szóval nagybetűvel, például run (); vagy runFast ();
  • Állandók - nagybetűkkel, „_” betűvel kell elválasztani az egyes szavakat, például int MIN_WIDTH = 44; és int MAX_WIDTH = 99;
  • Változó - egy név, amely elmondja a program olvasójának, hogy a változó mit képvisel, azaz ha teszteredményt tárol, akkor válassza a fokozatot vs var1. Tartsa rövid a változóneveket, ne kerüljön bele a metaadatokba.
// Prefer () - a változónevek rövidek, és írják le, mit tárol
int schoolId;
int [] filtersSchoolIds;
int [] uniqueSchooldIds;
Térkép  usersById;
Karakterlánc értéke;
// Kerülje (x) - Túl részletes a változó elnevezése
int schoolIdentificationNumber;
int [] userProvidedSchoolIds;
int [] schoolIdsAfterRemovingDuplicates;
Térkép  idToUserMap;
String valueString;

Ne feledje - a változónévnek rövidnek kell lennie, és könnyen el kell mondania az olvasót, hogy milyen értéket képvisel. Használja meg ítéletét.

Előnyben részesítés és elkerülés

A formázás és a behúzás a kód megszervezéséről szól, hogy könnyebben olvasható legyen, és magában foglalja a távolságot, a sor hosszát, a becsomagolást és a töréseket stb.

  • Behúzás - Használjon 2 vagy 4 helyet, és maradjon következetes
  • Sor hossza - Legfeljebb 70-120 karakter, az olvashatóságotól függően. Fontos, hogy elkerüljük a vízszintes görgetést és a vonal törését vessző és operátor után.

Módszerek - Itt található a legjobb gyakorlatok felsorolása

// Preferálja () A sortörések tetszőlegesek és vessző után szünetek.
String downloadAnInternet (Internet Internet, Csövek,
    Blogoszféra blogok, Összeg  sávszélesség) {
  tubes.download (internet);
}
// Kerülje (x) A módszer nehezen diffundálható, és ez a módszer testéhez tartozik
String downloadAnInternet (Internet Internet, Csövek,
    Blogoszféra blogok, Összeg  sávszélesség) {
    tubes.download (internet);
}
// Előnyben részesíti () 8 (2 vagy 4 kettős) szóköz hozzáadása a mély behúzáshoz
privát statikus szinkronizált horkingLongMethodName (int anArg,
        Object elseArg, String yetAnotherArg,
        Object andStillAnother) {
  ...
}
// Előnyben részesíti () Egyszerű szkennelés és extra oszloptér.
nyilvános karakterlánc letöltésAnInternet (
    Internet Internet,
    Csövek csövek,
    Blogosphere blogok,
    Összeg  sávszélesség) {
  tubes.download (internet);
  ...
}
Egy egységteszt ezt megkapta

If-check - az IMO jól formázott kódot írva megkönnyíti a helyesírási hibák és hibák észlelését a szerző és a kód-áttekintők számára, lásd alább:

// Kerülje (x) Ne hagyja ki a {}
if (feltétel)
  nyilatkozat;
// Kerülje (x)
ha (x <0) negatív (x);
// Kerülje (x)
if (a == b && c == d) {
...
}
// Előnyben részesíti ()
if ((a == b) && (c == d)) {
...
}
// Előnyben részesíti ()
if (feltétel) {
  kimutatások;
} máshol, ha (feltétel) {
  kimutatások;
} máshol, ha (feltétel) {
  kimutatások;
}
// Kerülje (x)
if ((1. feltétel és 2. feltétel)
    || (feltétel3 && feltétel4)
    ||! (5. feltétel és 6. feltétel)) {// BAD WRAPS
    doSomethingAboutIt (); // KÖNNYEN EZT A Vonalat elveszíteni
}
// Előnyben részesíti ()
if ((1. feltétel és 2. feltétel)
        || (feltétel3 && feltétel4)
        ||! (5. feltétel és 6. feltétel)) {
    doSomethingAboutIt ();
}

Ternáriumi operátor - és az alábbiakban ajánlott gyakorlatok

alpha = (aLongBooleanExpression)? béta: gamma;
alpha = (aLongBooleanExpression)? beta
        : gamma;
alpha = (aLongBooleanExpression)
        ? beta
        : gamma;

Kapcsoló - Amikor váltani kell, akkor a legjobb gyakorlat

  • Mindig legyen alapértelmezett eset, kód nélkül is
  • A / * gombbal áthúzhat a * / jelöléssel, hogy jelezze, hogy a vezérlés a következő esetre esik
kapcsoló (állapot) {
  ABC eset:
    kimutatások;
  / * átesik * /
  DEF eset:
    kimutatások;
    szünet;
  alapértelmezett:
    kimutatások;
     szünet;
}

Kivételüzenetek - Kivétel kivételével itt vannak jó és rosszul bevágott üzenetek mintái.

// Kerülje (x) - Nem könnyű olvasni
dobjon új IllegalStateException ("A kérés feldolgozása sikertelen" + request.getId ()
    + "felhasználó számára" + felhasználó.getId () + "lekérdezés:" "+ lekérdezés.getText ()
    + "" ");
// Előnyben részesíti () - meglehetősen könnyebben olvasható
dobjon új IllegalStateException ("Feldolgozás nem sikerült"
    + "kérés" + request.getId ()
    + "felhasználó számára" + user.getId ()
    + "query: '" + query.getText () + "'");

Iteratorok és patakok - A patakok egyre gyakoribbak, és időnként nagyon bonyolultak is lehetnek, ezért fontos, hogy behúzzuk a könnyű olvashatóság érdekében.

// Kerülje (x) - Nem könnyű olvasni
Iratálható  modulok = ImmvableList.  builder (). Add (new LifecycleModule ())
    .add (új AppLauncherModule ()). addAll (application.getModules ()). build ();
// Előnyben részesíti () - meglehetősen könnyebben olvasható
Iterábilis  modulok = ImmvableList.  builder ()
    .add (új LifecycleModule ())
    .add (új AppLauncherModule ())
    .addAll (application.getModules ())
    .épít();
Csak kövesse a kódolási szabványt - valójában bármilyen

Nyilatkozatok és feladatok - Soronként egy nyilatkozat ajánlott, mivel ösztönzi az észrevételeket az alábbiak szerint.

// Előnyben részesíti ()
int szint; // behúzási szint
int sizeMeter; // a táblázat mérete
// Kerülje az (x) pontot a fentiek mellett
int szint, sizeMeter;
// Prefer () - Az egység beillesztése a változó névbe vagy típusába
hosszú közvélemény-kutatás;
int fileSizeGb;
Összeg  fileSize;
// Kerülje el a (x) típusú keverést
int foo, fooarray [];
// Kerülje (x) - Ne válassza el vesszővel
Format.print (System.out, “hiba”), exit (1);
// Kerülje (x) többszörös hozzárendelést
fooBar.fChar = barFoo.lchar = 'c';
// Kerülje a (x) beágyazott hozzárendeléseket a teljesítmény növelése érdekében // vagy mentse el a sort. Bűnös vagyok ebben: (
d = (a = b + c) + r;
// Előnyben részesíti () fent
a = b + c;
d = a + r;
// Előnyben részesíti ()
Karakterlánc [] args
// Kerülje (x)
Húros karok []
// Előnyben részesíti () Az "1" szóval való összetéveszthetőség elkerülése érdekében hosszan használja az "L" -t, az "l" helyett
hosszú időtúllépés = 3000000000L;
// Kerülje (x) - Nehéz megmondani, hogy az utolsó betű l és nem 1
hosszú időtúllépés = 3000000000 l;

A deklarációkat csak a mondatok elejére tegye (A mondat kódját göndör zárójelek veszik körül {és}). Ne várja meg a változók deklarálását az első felhasználásig; összezavarhatja az óvatos programozót, és akadályozhatja a kód hordozhatóságát a hatókörön belül.

// Előnyben részesíti () a blokk elején.
public void doSomething () {
  mi létezik; // a módszerblokk kezdete
  if (feltétel) {
    int someFlag; // az „if” mondat eleje
    ...
  }
}

Fontos az is, hogy elkerüljük a helyi nyilatkozatokat, amelyek elrejtik a magasabb szintű nyilatkozatokat, és kerüljük az összetévesztéseket, amint az alább látható

int szám;
...
public void doSomething () {
  if (feltétel) {
    int szám; // ELKERÜLNI!
    ...
  }
  ...
}

Távolságok és sorok törése - Kerülje a kísértést, hogy 1–2 kód sort ment az olvashatóság rovására. Itt van a bevált gyakorlatok a távolság és az üres sorok vonatkozásában (ha a szóköz megváltoztatja)

  • Egy (1) üres sor a módszerek és a tavaszi fejlesztők között két (2) üres sort javasol a konstruktorok, statikus blokk, mezők és belső osztály után
  • Szóköz operátorok, azaz használja int foo = a + b + 1; int foo felett = a + b + 1;
  • Távolítsa el az összes bináris operátort a „.” Kivételével az operandusoktól szóközzel
  • A „{” nyitott zárójelek ugyanazon sor végén jelennek meg, mint a nyilatkozat vagy a módszer, a záró zárójelekkel a „}” pedig egy sort indít
// Előnyben részesíti () - szóköz a „rövid idő” után és a „(”) előtt
míg (igaz) {
  ...
}
// Kerülje (x) - a fentiekkel ellentétben nincs szóköz
míg (igaz) {
  ...
}
// Előnyben részesíti () - Nincs szóköz a "doSomething" és a "("
public void doSomething () {
  ...
}
// Kerülje (x) - a szóköz felett
public void doSomething () {
  ...
}
// Prefer () - Szóköz hozzáadása egy argumentum után
public void doSomething (int a, int b) {
  ...
}
// Előnyben részesíti () - Távolság az operandus és az operátorok között (azaz +, =)
a + = c + d;
a = (a + b) / (c * d);
míg (d ++ = s ++) {
  N ++;
}

Dokumentáció és megjegyzések

Érdemes megemlíteni, hogy szinte minden kód megváltozik élettartama alatt, és előfordul, hogy Ön vagy valaki megpróbálja kitalálni, hogy egy komplex kódblokk, módszer vagy osztály célja, kivéve, ha egyértelműen leírja. A valóság szinte mindig a következő

Előfordul, hogy a bonyolult kóddarab, módszer, osztály kommentálása nem ad hozzáadott értéket vagy szolgálja célját. Ez általában akkor történik, amikor kommentálnak.

A megjegyzéseket arra kell felhasználni, hogy áttekintést nyújtsanak a kódról, és olyan kiegészítő információkat nyújtsanak, amelyek nem állnak rendelkezésre a kódban. Kezdjük el. Kétféle megjegyzés létezik

Végrehajtási megjegyzések - a kód kommentálására vagy a kód adott megvalósításával kapcsolatos megjegyzésekre szolgálnak.

Dokumentációs megjegyzések - célja a kód specifikációjának leírása végrehajtás nélküli szempontból, amelyet a fejlesztőknek kell elolvasniuk, akiknek nem feltétlenül kell rendelkezniük a forráskóddal.

A kommentárok gyakorisága néha a kód rossz minőségét tükrözi. Ha úgy érzi, hogy hozzászólást kell fűznie, fontolja meg a kód átírását, hogy világosabb legyen.

A megvalósítás típusai

Az alább látható módon négy (4) típusú végrehajtási megjegyzés található meg

  • Megjegyzés blokkolása - lásd az alábbi példát
  • Egysoros megjegyzés - ha a megjegyzés nem haladja meg a sort
  • Kommentárok lezárása - Nagyon rövid megjegyzés a jobb oldalra került
  • A sor végének megjegyzés - elkezdi az új sorra folytatódó megjegyzést. Kommentálhat egy teljes sort, vagy csak egy részletet. Ezt nem szabad egymás utáni sorokban használni szöveges megjegyzésekhez; azonban felhasználható egymást követő több sorban a kódrészletek kommentálására.
// Megjegyzés blokkolása
/ *
 * Használat: leírja a fájlokat, metódusokat, adatszerkezeteket
 * és algoritmusok. Használható az egyes fájlok elején és
 * minden módszer előtt. Hosszú megjegyzésekhez használható, amelyek nem felelnek meg
 * egyvonalas. 1 Üres sor a blokk megjegyzés utáni folytatáshoz.
 * /
// Egysoros megjegyzés
if (feltétel) {
 / * Kezelje a feltételt. * /
  ...
}
// A végső megjegyzés
if (a == 2) {
 visszatér IGAZ; /* különleges eset */
} más {
 visszatérésPrime (a); / * csak páratlan * esetén működik
}
// A sor végének megjegyzés
if (foo> 1) {
  // Csinálj dupla flip-et.
  ...
} más {
  hamis visszaadást; // Magyarázza meg miért itt.
}
// if (sáv> 1) {
//
// // Csinálj háromszoros flip-et.
// ...
//}
//más
// hamis visszatérés;

Dokumentációs megjegyzések (azaz Javadoc)

A Javadoc egy olyan eszköz, amely HTML dokumentációt állít elő a java kódból a / ** betűkkel kezdődő és * / / jelző kommentárok felhasználásával - lásd a Wikipediaban a Javadoc működéséről, vagy csak az olvasásról.

Íme egy példa Javadocról

/ **
 * Olyan képobjektumot ad vissza, amelyet a képernyőre lehet festeni.
 * Az url argumentumnak abszolút {@link URL} értéket kell megadnia. A név
 * argumentum egy specifikátor, amely viszonyul az url argumentumhoz.
 * 

 * Ez a módszer mindig azonnal visszatér, függetlenül attól, hogy a  * kép létezik. Amikor ez az applet megpróbálja felhívni a képet  * A képernyő, az adatok betöltődnek. A grafikai primitívumok  * amelyek a képet rajzolják, fokozatosan festik meg a képernyőt.  *  * @param url abszolút URL, amely megadja a kép alaphelyét  * @param nevezze meg a kép helyét az url argumentumhoz viszonyítva  * @küldje vissza a képet a megadott URL-en  * @ Lásd a képet  * /  public image getImage (URL url, karakterlánc neve) {         próbálja meg {             return getImage (új URL (URL, név));         } fogás (MalformedURLException e) {             visszatérés null;         }  }

És a fentiek eredményeként HTML formátum lesz, ha a javadoc a fenti kóddal szemben fut

További információ itt található

Íme néhány kulcscímke, amelyek segítségével javíthatja a generált java dokumentáció minőségét.

@author => @author Raf
@code => {@code A  C}
@deprecated => @depreposed elavulási üzenet
@exception => @exception IOException dobva, amikor
@link => {@link package.class # tagcímke}
@param => @param paraméter-név leírása
@return => Mire szolgál a módszer
@see => @see "string" VAGY @see  
@since => A verzió jelzése, amikor egy nyilvánosan elérhető módszer hozzáadódik

A teljes listát és a részletesebb leírást itt találja

A Twitter kódolási szabványa javasolja a @author címke használatát

A kód élettartama során sokszor megváltoztathatja a tulajdonosokat, és a forrásfájl eredeti szerzője több iteráció után gyakran irreleváns. Sokkal jobb, ha a történelem és a Tulajdonosok fájljaiban bízunk a kódrészlet tulajdonjogának meghatározásakor.

Az alábbiakban bemutatunk néhány példát arra, hogyan lehet írásbeli kommentárt írni, amely ésszerű, a Twitter kódolási szabványában leírtak szerint

// Rossz.
// - A doc nem mond semmit, amit a módszer deklaráció nem tett.
// - Ez a „töltődokumentum”. Megtenné a stílusellenőrzést, de
senkinek sem segít.
/ **
 * Húr felosztva.
 *
 * @param s Karakterlánc.
 * @return A húrok listája.
 * /
Lista  split (String s);
// Jobb.
// - Tudjuk, hogy mi osztja a módszert.
// - Még mindig meghatározatlan viselkedés.
/ **
 * Húr felosztása a hézagra.
 *
 * @param s A felosztandó karakterlánc A {@code null} karakterláncot üres karakterláncként kezelik.
 * @return A bemeneti szóközökkel elválasztott részeinek listája.
 * /
Lista  split (String s);
// Nagy.
// - Lefed egy újabb él esetét.
/ **
 * Húr felosztása a hézagra. Ismételt szóköz karakterek
 * összeomlottak.
 *
 * @param s A felosztandó karakterlánc A {@code null} karakterláncot üres karakterláncként kezelik.
 * @return A bemeneti szóközökkel elválasztott részeinek listája.
 * /
Lista  split (String s);

Fontos, hogy profi legyen, amikor megjegyzéseket ír

// Kerülje (x)
// Nagyon utálom az xml / szappant, miért nem teheti ezt értem !?
próbálja meg {
  userId = Integer.parseInt (xml.getField ("id"));
} fogás (NumberFormatException e) {
  ...
}
// Előnyben részesíti ()
// TODO (Jim): A mező ellenőrzése a könyvtárban.
próbálja meg {
  userId = Integer.parseInt (xml.getField ("id"));
} fogás (NumberFormatException e) {
  ...
}

Fontos szem előtt tartani, hogy ne írja felül a felülbírált módszert, kivéve, ha a végrehajtás megváltozott.

És itt van még néhány szempont, amelyet figyelembe kell venni

  • Kerülje a helyettesítő karakterek behozatalát - a Twitter kódolási szabványaiban leírtak szerint az osztály forrása kevésbé világos. Az Eclipse és az IntelliJ felhasználók keverékével rendelkező csapatban dolgozom, és rájöttem, hogy az Eclipse megszünteti a helyettesítő karakterek behozatalát, és az IntelliJ bemutatja. Valószínűleg van egy lehetőség annak kikapcsolására is, csak szerettem volna rámutatni a két alapértelmezett beállítására.
  • A felülíráshoz mindig használja a @Override kommentárt
  • Ösztönözze a @Nullable használatát, ha egy mező vagy módszer null értékű
  • Használjon speciális megjegyzéseket a jövőbeli munkához, és ne felejtsük el hivatkozni magadra, hogy mások is tudják, kinek kell kitölteniük Y kérdésüket ahelyett, hogy kitalálnák, eltávolítanák vagy ellenőriznék a hibájukat, hogy megtalálják, ki adta hozzá. Egyes IDE-k, például az Eclipse és az IntelliJ szintén segítenek ezek felsorolásában a könnyű hozzáférés és emlékeztető számára.
// FIXME (Raf): Műveleti üzenet írja le, hogy mit kell tennie
// TODO (Raf): Műveleti üzenet írja le, hogy mit kell tennie

A végső játék az, hogy olyan kódot írjon, amely megkönnyíti a jövőbeli szerzők és karbantartók életét.

A vége játék

Egyéb releváns olvasmányok

A tiszta, jól felépített, könnyen olvasható és karbantartható kódíráshoz kapcsolódó releváns cikkek felsorolása. Ha többet szeretne olvasni, feltétlenül javasolja az alábbiakat

és egy jó lista a tiszta kód írásához