Trumpa „Java“ kodavimo geriausios praktikos santrauka

remiantis kodavimo standartais, kuriuos teikia „Oracle“, „Google“, „Twitter“ ir „Spring Framework“

Šio straipsnio tikslas yra pateikti trumpą atliktų darbų santrauką ir, kitaip tariant, nenorėti ir vengti, remiantis technologinių gigantų, tokių kaip „Oracle“, „Google“, „Twitter“ ir „Spring Framework“, kodavimo standartais.

Galbūt sutiksite su kai kuriomis geriausios praktikos pavyzdžiais, kurie yra čia, ir tai yra visiškai gerai, jei yra koks nors kodavimo standartas.

Kodėl pirmiausia reikia kodavimo standartų? Yra daug gerų priežasčių, jei jūs ją „Google“ naudojate, ir aš jums pateiksiu šią iliustraciją

Kodavimo standartų dokumentas gali būti ilgas ir nuobodus. Šis straipsnis „vyšnios“ renka bitus ir gabalėlius iš „Google“, „Oracle“, „Twitter“ ir „Spring“ kodavimo konvencijų. Jo tikslas yra suteikti jums lengvai sekamą ir mažiau nuobodų praktikos rinkinį, kad jūsų kodas būtų lengvai skaitomas ir prižiūrimas.

Beveik visada prisijungsite prie komandų, dirbančių su esama programine įranga, ir yra nemaža tikimybė, kad dauguma autorių pasitraukė arba perėjo prie skirtingų projektų, palikdami jums daugybę kodų, kurie priverčia suabejoti žmonija.

Pasinerkime į geriausių įvairių kodavimo standartų praktiką.

„Java“ šaltinio failas

Tai, kas yra geriausia praktika, kai kalbama apie „Java“ šaltinio failus:

  • Šaltinio failo ilgis yra mažesnis nei 2 000 kodo eilučių
  • Šaltinio failas yra sutvarkytas su dokumento komentarais, paketo deklaracija, po kurio seka klasės komentaras, importuojamas sugrupuotas (statinis paskutinis), klasės / sąsajos parašas ir pan., Kaip parodyta žemiau
paketas com.example.model;
/ **
 * Programos kūrėjų perskaityta perspektyva be įgyvendinimo
 * kurie gali nebūtinai turėti šaltinio kodą
 *
 * @autoras x, y, z
 * @data
 * @versija
 * @ autorinės teisės
 *
 * /
importuoti com.example.util.FileUtil;
/ *
 * Pasirenkamas konkrečios klasės komentaras
 *
 * /
visuomenės klasė „SomeClass“ {
  // Statiniai kintamieji matomumo tvarka
  viešas statinis galutinis sveikasis skaičius PUBLIC_COUNT = 1;
  statinis galutinis sveikasis skaičius PROTECTED_COUNT = 1;
  privatus statinis galutinis sveikasis skaičius PRIVATE_COUNT = 1;
  // Egzemplioriaus kintamieji matomumo tvarka
  viešas stygos pavadinimas;
  Eilutės pašto kodas;
  privatus stygos adresas;
  // Konstruktorius ir perkrautas eilės tvarka
  viešas „SomeClass“ () {}
  public „SomeClass“ (eilutės pavadinimas) {
    this.name = vardas;
  }
  // Metodai
  vieša eilutė doSomethingUseful () {
    grįžti „Kažkas naudingo“;
  }
  // getters, setters, equals, hashCode ir toString pabaigoje
}

Pavadinimas

Klasių ir sąsajų pavadinimai yra „CamelCase“, todėl rekomenduojama vartoti visą žodį ir vengti akronimų / santrumpų. Pavyzdžiui, klasės „Raster“ arba klasės „ImageSprite“

  • Paketas - pavadinimai com.deepspace per com.deepSpace arba com.deep_space
  • Failų pavadinimai yra „CamelCase“ ir baigiasi .java, atitinkančiu klasės pavadinimą. Kiekvienoje byloje yra viena viešoji klasė su kiekviena aukščiausio lygio klase
  • Metodas - vardai turi būti veiksmažodžiai mišriomis raidėmis, kiekvienas žodis rašomas didžiosiomis raidėmis, pvz., Run (); arba „runFast“ ();
  • Konstantos - turėtų būti didžiosios raidės su „_“, atskiriančios kiekvieną žodį, pvz., Int MIN_WIDTH = 44; ir int MAX_WIDTH = 99;
  • Kintamasis - vardas, kuris programos skaitytojui nurodo, ką reiškia kintamasis, t. Y. Jei kaupiate bandomąjį pažymį, tada pasirinkite pažymį vs var1. Laikykite trumpus kintamųjų pavadinimus, kad neįtrauktumėte metaduomenų.
// Pirmenybė () - kintamųjų pavadinimai trumpi ir apibūdinkite, ką jie saugo
int schoolId;
int [] filtersSchoolIds;
int [] unikali mokykla;
Žemėlapis  usersById;
Eilutės reikšmė;
// Venkite (x) - per daug detalus kintamųjų įvardijimas
int schoolIdentificationNumber;
int [] userProvidedSchoolIds;
int [] schoolIdsAfterRemovingDuplicates;
Žemėlapis  idToUserMap;
Stygos reikšmė styga;

Atminkite - kintamojo vardas turėtų būti trumpas ir lengvai pranešti skaitytojui, kokia jo reikšmė. Pasinaudokite savo vertinimu.

Pirmenybė ir venkite

Formatavimas ir įtraukimas yra susiję su jūsų kodo tvarkymu, kad būtų lengva jį perskaityti. Tai apima tarpus, eilutės ilgį, įvyniojimus ir pertraukas ir pan.

  • Įtrauka - naudokite 2 arba 4 tarpus ir būkite nuoseklūs
  • Eilutės ilgis - nuo 70 iki 120 ženklų, atsižvelgiant į įtaką skaitomumui. Svarbu panaikinti horizontaliojo slinkties poreikį ir pertraukti linijas po kablelio ir operatoriaus.

Metodai - pateikiame geriausios praktikos sąrašą

// Pageidautina () Linijų pertraukos yra savavališkos ir pertraukiamos po kablelio.
„Internetinis internetas, vamzdeliai,
    „Blogosferos“ tinklaraščiai, kiekis  pralaidumas) {
  tube.download (internetas);
}
// Vengti (x) Sunkiai diferencijuojamas metodas priklauso nuo metodo kūno
„Internetinis internetas, vamzdeliai,
    „Blogosferos“ tinklaraščiai, kiekis  pralaidumas) {
    tube.download (internetas);
}
// Pirmenybė () Pridėkite 8 (dvigubus 2 arba 4) tarpus giliai įtraukai
privatus statinis sinchronizuotas horkingLongMethodName (int anArg,
        Objektas elseArg, eilutė darAnotherArg,
        Objektas andStillAnother) {
  ...
}
// Pirmenybė () Lengvas nuskaitymas ir papildomos vietos stulpelyje.
„Public String downloadAnInternet“ (
    Internetas internetas,
    Vamzdžių vamzdžiai,
    „Blogosferos“ tinklaraščiai,
    Suma  pralaidumas) {
  tube.download (internetas);
  ...
}
Vieneto testas būtų sugavęs tą

Jei patikrinimai - TJO, rašydami tinkamai suformatuotą kodą, leidžia lengvai pastebėti rašybos klaidas ir klaidas autoriui ir kodų apžvalgininkams, žr. Toliau:

// Venkite (x) Nepraleiskite {}
if (sąlyga)
  pareiškimas;
// Venkite (x)
jei (x <0) neigiamas (x);
// Venkite (x)
if (a == b && c == d) {
...
}
// Pirmenybė ()
if ((a == b) && (c == d)) {
...
}
// Pirmenybė ()
if (sąlyga) {
  teiginiai;
} dar jei (sąlyga) {
  teiginiai;
} dar jei (sąlyga) {
  teiginiai;
}
// Venkite (x)
if ((sąlyga1 ir sąlyga2)
    || (sąlyga 3 ir& sąlyga 4)
    ||! (sąlyga5 ir sąlyga6)) {// BAD WRAPS
    doSomethingAboutIt (); // ŠIĄ LINIJĄ PRIVALOMA MELYTI
}
// Pirmenybė ()
if ((sąlyga1 ir sąlyga2)
        || (sąlyga 3 ir& sąlyga 4)
        ||! (sąlyga5 ir sąlyga6)) {
    doSomethingAboutIt ();
}

Trejybės operatorius - ir toliau rekomenduojama praktika

alfa = („aLongBooleanExpression“)? beta: gama;
alfa = („aLongBooleanExpression“)? beta
        : gama;
alfa = („aLongBooleanExpression“)
        ? beta
        : gama;

Perjungti - kai reikia perjungti, tai geriausia praktika

  • Visada turėkite numatytąjį atvejį, net neturėdami kodo
  • Mygtukais / * nukrypsta per * /, jei norite nurodyti, kad valdiklis nukryps į kitą atvejį
jungiklis (būklė) {
  atvejis ABC:
    teiginiai;
  / * patenka per * /
  atvejis DEF:
    teiginiai;
    pertrauka;
  numatytas:
    teiginiai;
     pertrauka;
}

Išimties pranešimai - kai nurodoma išimtis, pateikiami gerų ir blogai įterptų pranešimų pavyzdžiai.

// Venkite (x) - nelengva skaityti
mesti naują „IllegalStateException“ („Nepavyko apdoroti užklausos“ + request.getId ()
    + "vartotojui" + vartotojas.getId () + "užklausa:" "+ užklausa.getText ()
    + "'");
// Pirmenybė () - gana lengvai skaitoma
mesti naują „IllegalStateException“ („Nepavyko apdoroti“
    + „užklausa“ + užklausa.getId ()
    + „vartotojui“ + user.getId ()
    + "užklausa: '" + užklausa.getText () + "'");

Iteratoriai ir srautai - srautai tampa vis dažnesni ir kartais gali būti labai sudėtingi, todėl svarbu, kad būtų lengva perskaityti įtrauką.

// Venkite (x) - nelengva skaityti
Pakartojami  moduliai = ImmvableList.  Builder (). Add (new LifecycleModule ())
    .add (naujas AppLauncherModule ()). addAll (application.getModules ()). build ();
// Pirmenybė () - gana lengvai skaitoma
Pastovūs  moduliai = ImmvableList.  kūrėjas ()
    .add (naujas „LifecycleModule“)
    .add (naujas „AppLauncherModule“)
    .addAll (application.getModules ())
    .build ();
Tiesiog laikykitės kodavimo standarto - bet kokio tikrai

Deklaracijos ir užduotys - kiekvienoje eilutėje rekomenduojama pateikti vieną deklaraciją, nes ji skatina pateikti komentarus, kaip parodyta žemiau.

// Pirmenybė ()
vidinis lygis; // įtraukos lygis
int dydisMeter; // lentelės dydis
// Venkite (x) aukščiau pateikto
vidinis lygis, dydisMetras;
// Pirmenybė () - Įtraukite vienetą į kintamąjį pavadinimą ar tipą
ilgas apklausa tarpukariu;
int fileSizeGb;
Suma  failo dydis;
// Venkite (x) maišyti tipus
int foo, fooarray [];
// Venkite (x) - neišskirkite kableliais
Format.print („System.out“, „klaida“), išeiti (1);
// Venkite (x) daugybės priskyrimų
fooBar.fChar = barFoo.lchar = 'c';
// Venkite (x) įterptinių užduočių bandydami padidinti našumą // arba išsaugokite eilutę. Aš dėl to kaltas :(
d = (a = b + c) + r;
// Pirmenybė () viršuje
a = b + c;
d = a + r;
// Pirmenybė ()
Stygos [] args
// Venkite (x)
Styginių lankai []
// Pirmenybė () Norėdami išvengti painiavos su 1, ilgai naudokite „L“, o ne „l“
ilgas laikas = 3000000000L;
// Venkite (x) - sunku pasakyti, paskutinė raidė yra l, o ne 1
ilgas laikas = 3000000000l;

Pateikite deklaracijas tik blokų pradžioje (Blokas yra kodas, apsuptas garbanomis {ir}). Nelaukite, kol deklaruosite kintamuosius, kol jie nebus naudojami pirmą kartą; tai gali supainioti neatsargų programuotoją ir sutrukdyti kodo perkeliamumą šioje srityje.

// Pirmenybė () deklaruojama bloko pradžioje.
public void doSomething () {
  kas yra tiesiogiai; // metodo bloko pradžia
  if (sąlyga) {
    int kaiFlag; // „if“ bloko pradžia
    …
  }
}

Taip pat svarbu vengti vietinių deklaracijų, kuriose slepiamos aukštesnio lygio deklaracijos, ir vengti painiavos, kaip parodyta žemiau.

int skaičius;
...
public void doSomething () {
  if (sąlyga) {
    int skaičius; // VENKITE!
    ...
  }
  ...
}

Tarpai ir eilučių pertraukos - venkite pagundos sutaupyti 1–2 kodo eilutes skaitomumo sąskaita. Čia yra geriausia praktika, kai kalbama apie tarpus ir tuščias eilutes (baltas tarpas tikrai pakeis)

  • Viena (1) tuščia eilutė tarp metodų ir „Spring“ kūrėjų rekomenduoja dvi (2) tuščias eilutes po konstruktorių, statinį bloką, laukus ir vidinę klasę.
  • Tarpų operatoriai, t. Y. Naudoti int foo = a + b + 1; per int foo = a + b + 1;
  • Atskirkite visus dvejetainius operatorius, išskyrus „.“ Nuo operandų, naudodami tarpą
  • Atidarytas petnešas „{“ rodomas tos pačios eilutės, kaip deklaracijos pareiškimas ar metodas, pabaigoje, o užsegimas „}“ pradeda eilutę, savaime įbrėžtą.
// Pirmenybė () - tarpas po „kol“ ir prieš „(“
o (tiesa) {
  ...
}
// Venkite (x) - skirtingai nei aukščiau, nėra vietos
tuo tarpu (tiesa) {
  ...
}
// Pageidautina () - nėra tarpo tarp „doSomething“ ir „(“
public void doSomething () {
  ...
}
// Venkite (x) - skirtingai nuo aukščiau esančios vietos
public void doSomething () {
  ...
}
// Pirmenybė () - pridėkite tarpą po argumento
public void doSomething (int a, int b) {
  ...
}
// Pirmenybė () - tarpas tarp operando ir operatorių (t.y. +, =)
a + = c + d;
a = (a + b) / (c * d);
o (d ++ = s ++) {
  n ++;
}

Dokumentacija ir komentarai

Verta paminėti, kad beveik visas kodas keičiasi per visą jo gyvavimo laiką ir kai kada jūs ar kas nors bandys išsiaiškinti, ką ketina atlikti sudėtingas kodo blokas, metodas ar klasė, nebent tai būtų aiškiai aprašyta. Realybė beveik visada tokia

Kartais būna, kad sudėtingas kodo, metodo, klasės komentaras neprideda jokios vertės arba neatitinka tikslo. Paprastai tai atsitinka komentuojant.

Komentarai turėtų būti naudojami pateikiant kodo apžvalgas ir suteikiant papildomos informacijos, kurios nėra pačiame kode. Pradėkime. Yra dviejų tipų komentarai

Įdiegimo komentarai - skirti komentuoti kodą arba pakomentuoti tam tikrą kodo įgyvendinimą.

Dokumentacijos komentarai - skirti apibūdinti kodo specifikaciją iš diegimo perspektyvos, kad ją perskaitytų kūrėjai, kurie, ko gero, nebūtinai turi šaltinio kodą.

Komentarų dažnis kartais atspindi prastą kodo kokybę. Kai jaučiatės priversti pridėti komentarą, apsvarstykite galimybę perrašyti kodą, kad jis būtų aiškesnis.

Įgyvendinimo komentarų tipai

Yra keturi (4) įgyvendinimo komentarų tipai, kaip parodyta žemiau

  • Blokuoti komentarą - žiūrėkite žemiau pateiktą pavyzdį
  • Vienos eilutės komentaras - kai komentaras yra ne ilgesnis nei eilutė
  • Komentarų pabaiga - labai trumpas komentaras perkeltas į dešinę
  • Eilutės pabaigos komentaras - pradedamas komentaras, kuris tęsiamas prie naujos eilutės. Tai gali komentuoti visą eilutę arba tik dalinę eilutę. Jis neturėtų būti naudojamas kelioms eilėms teksto komentaruose; tačiau jis gali būti naudojamas keliose eilutėse kodo dalims komentuoti.
// Blokuoti komentarą
/ *
 * Naudojimas: Pateikiamas failų, metodų, duomenų struktūrų aprašymas
 * ir algoritmai. Galima naudoti kiekvieno failo pradžioje ir
 * prieš kiekvieną metodą. Naudojamas ilgiems komentarams, kurie netinka
 * viena linija. 1 tuščia eilutė, jei norite tęsti po bloko komentaro.
 * /
// Vienos eilutės komentaras
if (sąlyga) {
 / * Tvarkykite būklę. * /
  ...
}
// Galutinis komentaras
if (a == 2) {
 grąžinti TIESA; /* ypatinga byla */
} Kitas {
 grįžti isPrime (a); / * veikia tik keistam *
}
// Eilutės pabaigos komentaras
if (foo> 1) {
  // Daryk dvigubą apversmą.
  ...
} Kitas {
  grąžinti klaidingą; // Paaiškink, kodėl čia.
}
// if (baras> 1) {
//
// // Atlikite trigubą apversmą.
// ...
//}
//Kitas
// grąžinti klaidingą;

Dokumentacijos komentarai (pvz., „Javadoc“)

„Javadoc“ yra įrankis, kuris sugeneruoja HTML dokumentus iš jūsų „Java“ kodo, naudodamas komentarus, prasidedančius / ** ir pasibaigiančiais * / - daugiau informacijos apie tai, kaip „Javadoc“ veikia, ar tiesiog skaitykite kartu, rasite Vikipedijoje.

Čia yra „Javadoc“ pavyzdys

/ **
 * Grąžina vaizdinį objektą, kurį vėliau galima nupiešti ekrane.
 * URL argumentas turi nurodyti absoliutų {@link URL}. Pavadinimas
 * argumentas yra specifikatorius, palyginti su URL argumentu.
 * 

 * Šis metodas visada grįžta, neatsižvelgiant į tai, ar  * vaizdas egzistuoja. Kai ši programėlė bando piešti vaizdą  * ekranas, duomenys bus įkelti. Grafikos primityvai  * kurie piešia vaizdą, ekrane laipsniškai dažysis.  *  * @param url yra absoliutus URL, nurodantis pagrindinę vaizdo vietą  * @param pavadinkite vaizdo vietą, palyginti su URL argumentu  * @paverskite vaizdą nurodytu URL  * @ žiūrėti vaizdą  * /  public image getImage (URL adresas, eilutės pavadinimas) {         bandyti {             grąžinti „getImage“ (naujas URL (URL, vardas));         } sugauti („MalformedURLException e“) {             grąžinti nulinį;         }  }

Ir tai, kas išdėstyta aukščiau, patektų į HTML kodą, kai „javadoc“ vykdomas prieš aukščiau esantį kodą

Čia rasite daugiau

Čia yra keletas pagrindinių žymų, kurias galite naudoti kuriamos „Java“ dokumentacijos kokybei pagerinti.

@author => @author Rafas
@code => {@code A  C}
@deprecated => @depreposed atšaukimo pranešimas
@exception => @exception IOException išmetamas, kai
@link => {@link package.class # narys etiketė}
@param => @param parametro pavadinimo aprašymas
@return => Ką grąžina metodas
@see => @ see "string" ARBA @ žiūrėti  
@since => Norėdami nurodyti versiją, kai pridedamas viešai prieinamas metodas

Išsamų sąrašą ir išsamesnį aprašymą rasite čia

„Twitter“ kodavimo standartas pataria nenaudoti @author žymos

Kodas gali pakeisti rankas daugybę kartų per savo gyvenimą, ir gana dažnai pirminis šaltinio failo autorius neturi reikšmės po kelių pakartojimų. Manome, kad geriau pasitikėti įsipareigojimo istorija ir OWNERS failais, kad būtų galima nustatyti kodo rinkinį.

Toliau pateikiami pavyzdžiai, kaip galėtumėte parašyti įžvalgų dokumentacijos komentarą, kaip aprašyta „Twitter“ kodavimo standarte

// Blogai.
// - Dokumentas nieko nesako, kad metodo deklaracija to nepadarė.
// - Tai yra „užpildymo dokumentas“. Tai praeitų stiliaus patikrinimus, bet
niekam nepadeda.
/ **
 * Padalija eilutę.
 *
 * @param s Styga.
 * @return Styginių sąrašas.
 * /
Sąrašas  split (stygos);
// Geriau.
// - Mes žinome, koks metodas suskaidomas.
// - Vis dar neapibrėžtas elgesys.
/ **
 * Padalija eilutę tarpų.
 *
 * @param s eilutė, kurią reikia padalyti. {@Code null} eilutė traktuojama kaip tuščia eilutė.
 * @return Įvesties dalių, tarp kurių atskirtos vietos, sąrašas.
 * /
Sąrašas  split (stygos);
// Puiku.
// - Apima dar vieną kraštinį atvejį.
/ **
 * Padalija eilutę tarpų. Pakartotiniai tarpai su tarpais
 * yra sutraukti.
 *
 * @param s eilutė, kurią reikia padalyti. {@Code null} eilutė traktuojama kaip tuščia eilutė.
 * @return Įvesties dalių, tarp kurių atskirtos vietos, sąrašas.
 * /
Sąrašas  split (stygos);

Rašant komentarus svarbu būti profesionaliu

// Venkite (x)
// Aš labai nekenčiu xml / muilo, kodėl jis negali to padaryti už mane !?
bandyti {
  userId = Integer.parseInt (xml.getField ("id"));
} pagauk („NumberFormatException e“) {
  ...
}
// Pirmenybė ()
// TODO (Jim): laukų patvirtinimas atliekamas bibliotekoje.
bandyti {
  userId = Integer.parseInt (xml.getField ("id"));
} pagauk („NumberFormatException e“) {
  ...
}

Svarbu nepamiršti dokumentuoti nepaisomo metodo, nebent pasikeitė diegimas.

Ir čia reikia atsiminti dar keletą punktų

  • Venkite pakaitos ženklų importo - kaip aprašyta „Twitter“ kodavimo standartuose, klasės šaltinis tampa ne toks aiškus. Aš dirbu komandoje, kurioje yra įvairių „Eclipse“ ir „IntelliJ“ vartotojų, ir sužinojau, kad „Eclipse“ pašalina pakaitos simbolių importą, o „IntelliJ“ tai pristato. Tikriausiai yra galimybė jį išjungti, tiesiog norėjau atkreipti dėmesį į nutylėjimą dviem.
  • Visada naudokite „@Override“ anotaciją, kai pakeisite
  • Skatinkite naudoti „@Nullable“, kai laukas ar metodas grąžina negaliojantį
  • Būsimam darbui pasinaudokite specialiais komentarais ir nepamirškite palikti nuorodos į save, kad kiti žinotų, kam užduoti savo Y klausimą, užuot spėliojantys, pašalinę jį ar patikrinę, kas jį kaltą, kad surastumėte. Kai kurie IDE, tokie kaip „Eclipse“ ir „IntelliJ“, taip pat padeda juos išvardyti, kad būtų galima lengvai juos pasiekti, ir priminimą.
// „FIXME“ („Raf“): Praktinis pranešimas apibūdina, ką reikia padaryti
// TODO („Raf“): Praktinis pranešimas apibūdina, ką reikia padaryti

Žaidimo pabaiga yra kodas, kuris palengvina būsimų autorių ir prižiūrėtojų gyvenimą.

Pabaigos žaidimas

Kita svarbi skaitymo medžiaga

Atitinkamų straipsnių, svarbių rašant švarų, gerai struktūruotą, lengvai skaitomą ir prižiūrimą kodą, sąrašas. Jei norite skaityti daugiau, būtinai rekomenduokite šiuos dalykus

ir dar vienas geras sąrašas patarimų, kaip rašyti švarų kodą