Īss Java kodēšanas paraugprakses kopsavilkums

balstoties uz Oracle, Google, Twitter un Spring Framework kodēšanas standartiem

Šī raksta mērķis ir sniegt jums ātru kopsavilkumu par paveikto, citiem vārdiem sakot, nedod priekšroku un neizvairās, pamatojoties uz kodēšanas standartiem no tādiem tehnoloģiju gigantiem kā Oracle, Google, Twitter un Spring Framework.

Varbūt jūs nepiekrītat dažiem šeit aprakstītajiem paraugprakses piemēriem, un tas ir pilnīgi labi, ja vien ir kāds kodēšanas standarts.

Kāpēc, pirmkārt, kodēšanas standarti? Ir daudz labu iemeslu, ja jūs to Google izmantojat, un es jums sniegšu šo ilustrāciju

Kodēšanas standartu dokuments var būt garš un garlaicīgs. Šajā rakstā iekļautie ķirši ievāc bitus un gabalus no kodēšanas konvencijām, kuras izstrādājuši Google, Oracle, Twitter un Spring, un tā mērķis ir sniegt jums viegli sekojošu un mazāk garlaicīgu darbību kopumu, lai jūsu kods būtu viegli lasāms un uzturējams.

Gandrīz vienmēr jūs pievienosities komandām, kas strādā pie esošās programmatūras, un pastāv diezgan liela iespēja, ka lielākā daļa autoru ir pametuši vai pārgājuši uz dažādiem projektiem, atstājot jūs iesprostotus ar kodu porcijām, kas liek apšaubīt cilvēci.

Padziļināsimies dažādu kodēšanas standartu paraugpraksē.

Java avota fails

Javas avota failos par labāko praksi tiek uzskatīts:

  • Avota faila garums ir mazāks par 2000 koda rindām
  • Avota fails tiek sakārtots ar dokumentācijas komentāru, paketes deklarāciju, kam seko klases komentārs, imports tiek grupēts (pēdējais statiskais), klases / interfeisa paraksts un tā tālāk, kā parādīts zemāk
pakete com.example.model;
/ **
 * Izstrādātājiem jālasa perspektīva bez ieviešanas
 * kam, iespējams, nav avota koda
 *
 * @autors x, y, z
 * @datums
 * @versija
 * @ autortiesības
 *
 * /
importēt com.example.util.FileUtil;
/ *
 * Izvēles klases komentārs
 *
 * /
sabiedriskā klase SomeClass {
  // Statiskie mainīgie redzamības secībā
  publiskais statiskais galīgais skaitlis PUBLIC_COUNT = 1;
  statiskais galīgais skaitlis PROTECTED_COUNT = 1;
  privāts statisks galīgais skaitlis PRIVATE_COUNT = 1;
  // instanču mainīgie redzamības secībā
  publiskais stīgu nosaukums;
  Virknes pasta indekss;
  privāta virknes adrese;
  // Konstruktors un pārslogots secīgā secībā
  publisks SomeClass () {}
  publisks SomeClass (stīgas nosaukums) {
    this.name = vārds;
  }
  // Metodes
  publiskā virkne doSomethingUseful () {
    atgriezt "Kaut ko noderīgu";
  }
  // getters, setters, equals, hashCode un toString beigās
}

Nosaukums

Klases un interfeisa nosaukumi ir CamelCase, un ieteicams lietot visu vārdu un izvairīties no akronīmiem / saīsinājumiem. Piemēram, klase Rastra vai klase ImageSprite

  • Komplekts - nosaukumi com.deepspace virs com.deepSpace vai com.deep_space
  • Failu nosaukumi ir CamelCase un beidzas ar .java, kas atbilst klases nosaukumam. Katrā failā ir viena publiskā klase ar katru faila augstāko klasi
  • Metode - nosaukumiem vajadzētu būt darbības vārdiem jauktos burtos ar katru iekšējo vārdu, izmantojot lielo burtu, piemēram, run (); vai runFast ();
  • Konstantes - jābūt lieliem ar “_”, atdalot katru vārdu, piemēram, int MIN_WIDTH = 44; un int MAX_WIDTH = 99;
  • Mainīgais - nosaukums, kas stāsta programmas lasītājam, ko mainīgais pārstāv, t.i., ja jūs glabājat testa atzīmi, tad izvēlieties atzīmi vs var1. Turiet mainīgo nosaukumus īsus, neiekļaujot metadatus.
// Dod priekšroku () - mainīgo nosaukumi ir saīsināti un apraksta, ko tas glabā
int schoolId;
int [] filtersSchoolIds;
int [] unikālāSkoldsIdi;
Karte  usersById;
Stīgas vērtība;
// Izvairieties (x) - Pārāk detalizēta mainīgo nosaukšana
int schoolIdentificationNumber;
int [] userProvidedSchoolIds;
int [] schoolIdsAfterRemovingDuplicates;
Karte  idToUserMap;
Stīgas vērtībaString;

Atcerieties - mainīgajam nosaukumam jābūt īsam un viegli norādiet lasītājam, kādu vērtību tas pārstāv. Izmantojiet savu spriedumu.

Dodiet priekšroku un izvairieties

Formatēšana un atkāpes ir saistītas ar koda sakārtošanu, lai padarītu to viegli lasāmu, un tas ietver atstarpes, līnijas garumu, aptinumus un pārtraukumus utt.

  • Izvilkums - izmantojiet 2 vai 4 atstarpes un uzturieties konsekventi
  • Rindas garums - no 70 līdz 120 rakstzīmēm atkarībā no lasāmības. Ir svarīgi novērst vajadzību pēc horizontālas ritināšanas un līnijas pārtraukumiem pēc komata un operatora.

Metodes - šeit ir paraugprakses saraksts

// Dodiet priekšroku () Līniju pārtraukumi ir patvaļīgi un pārtrūkst pēc komata.
Virkne downloadAnInternet (internets internets, Caurules,
    Blogosfēras emuāri, daudzums  joslas platums) {
  tube.download (internets);
}
// Izvairieties (x) Metode ir grūti diferencējama līdz metodes pamattekstam
Virkne downloadAnInternet (internets internets, Caurules,
    Blogosfēras emuāri, daudzums  joslas platums) {
    tube.download (internets);
}
// Dodiet priekšroku () dziļajam ievilkumam pievienojiet 8 (divreiz no 2 vai 4) atstarpes
privāta statiska sinhronizēta horkingLongMethodName (int anArg,
        Objekts citsArg, virkne vēlAnotherArg,
        Objekts unStillAnother) {
  ...
}
// Dod priekšroku () Vienkārša skenēšana un papildu vieta kolonnās.
publiskā virkne downloadAnInternet (
    Internets internets,
    Caurules caurules,
    Blogosfēras emuāri,
    Summa  joslas platums) {
  tube.download (internets);
  ...
}
Vienības pārbaude būtu to uztvērusi

Pārbaudes - ja SJO uzraksta labi formatētu kodu, tas autorei un kodu pārbaudītājiem ļauj viegli pamanīt pareizrakstības kļūdas un kļūdas, skatīt zemāk:

// Izvairieties (x) Neizlaist {}
ja (nosacījums)
  paziņojums, apgalvojums;
// Izvairieties (x)
ja (x <0) negatīvs (x);
// Izvairieties (x)
ja (a == b && c == d) {
...
}
// Dod priekšroku ()
ja ((a == b) && (c == d)) {
...
}
// Dod priekšroku ()
ja (nosacījums) {
  paziņojumi;
} cits, ja (nosacījums) {
  paziņojumi;
} cits, ja (nosacījums) {
  paziņojumi;
}
// Izvairieties (x)
if ((nosacījums1 un& nosacījums2)
    || (nosacījums3 un nosacījums4)
    ||! (nosacījums5 && nosacījums6)) {// BAD WRAPS
    doSomethingAboutIt (); // ĻOTI ŠO LĪNIJU VIENKĀRŠI IZMĒROT
}
// Dod priekšroku ()
if ((nosacījums1 un& nosacījums2)
        || (nosacījums3 un nosacījums4)
        ||! (nosacījums5 && nosacījums6)) {
    doSomethingAboutIt ();
}

Trīskāršais operators - un tālāk ir ieteikta prakse

alfa = (aLongBooleanExpression)? beta: gamma;
alfa = (aLongBooleanExpression)? beta
        : gamma;
alfa = (aLongBooleanExpression)
        ? beta
        : gamma;

Pārslēgt - ja ir jāmaina, tā ir labākā prakse

  • Vienmēr lietojiet noklusējuma gadījumu pat bez koda
  • Izmantojiet / * izkrīt caur * /, lai norādītu, ka vadības ierīce nonāk nākamajā gadījumā
slēdzis (stāvoklis) {
  gadījums ABC:
    paziņojumi;
  / * izkrīt caur * /
  lieta DEF:
    paziņojumi;
    pārtraukums;
  noklusējums:
    paziņojumi;
     pārtraukums;
}

Izņēmuma ziņojumi - ja tiek izmantots izņēmums, šeit ir labu un vāji iespiestu ziņojumu paraugi.

// Izvairieties (x) - to nav viegli lasīt
mest jaunu IllegalStateException (“Neizdevās apstrādāt pieprasījumu” + request.getId ()
    + "lietotājam" + lietotājs.getId () + "vaicājums:" "+ query.getText ()
    + "'");
// Dod priekšroku () - diezgan viegli lasīt
iemest jaunu IllegalStateException (“Neizdevās apstrādāt”
    + "pieprasījums" + pieprasījums.getId ()
    + "lietotājam" + user.getId ()
    + "vaicājums: '" + query.getText () + "'");

Iteratori un straumes - straumītes kļūst aizvien izplatītākas, un reizēm tās var būt ļoti sarežģītas, tāpēc ir svarīgi izdarīt ievilkumu, lai tās būtu viegli lasīt.

// Izvairieties (x) - to nav viegli lasīt
Iteatējami  moduļi = ImmvableList.  Builder (). Add (new LifecycleModule ())
    .add (jauns AppLauncherModule ()). addAll (application.getModules ()). build ();
// Dod priekšroku () - diezgan viegli lasīt
Iterami  moduļi = ImmvableList.  veidotājs ()
    .add (jauns LifecycleModule ())
    .add (jauns AppLauncherModule ())
    .addAll (application.getModules ())
    .būvēt();
Vienkārši ievērojiet kodēšanas standartu - jebkuru tiešām

Deklarācijas un uzdevumi - katrā rindā ir ieteicama viena deklarācija, jo tā rosina komentēt, kā parādīts zemāk.

// Dod priekšroku ()
int līmenis; // ievilkuma līmenis
int lielumsMeter; // tabulas izmērs
// Izvairieties no (x) par labu iepriekšminētajam
int līmenis, lielumsMeter;
// Dod priekšroku () - iekļaujiet vienību mainīgā nosaukumā vai tipā
ilga aptaujaIntervalMs;
int failsSizeGb;
Summa  fileSize;
// Izvairieties no (x) sajaukšanas veidiem
int foo, fooarray [];
// Izvairieties (x) - neatdaliet ar komatu
Format.print (System.out, “kļūda”), izeja (1);
// Izvairieties no (x) atkārtotas piešķiršanas
fooBar.fChar = barFoo.lchar = 'c';
// Izvairieties no (x) iegultiem uzdevumiem, mēģinot palielināt veiktspēju // vai saglabāt līniju. Es esmu pie tā vainīgs :(
d = (a = b + c) + r;
// Dodiet priekšroku () iepriekš
a = b + c;
d = a + r;
// Dod priekšroku ()
Stīgu [] args
// Izvairieties (x)
Stīgu balsti []
// Dodiet priekšroku () Lai “L” vietā ilgi sajauktu ar 1, izmantojiet “L”, nevis “l”
ilgs taimauts = 3000000000L;
// Izvairieties no (x) - grūti pateikt, pēdējais burts ir l, nevis 1
ilgs noildze = 3000000000l;

Deklarācijas ievietojiet tikai ierakstu sākumā (bloks ir kods, kuru ieskauj cirtaini iekavās {un}). Negaidiet mainīgo deklarēšanu līdz to pirmajai lietošanai. tas var sajaukt neuzmanīgu programmētāju un kavēt koda pārnesamību darbības jomā.

// Dod priekšroku () deklarēt bloka sākumā.
public void doSomething () {
  kas tieši klāt; // metodes bloka sākums
  ja (nosacījums) {
    int dažiFlag; // bloka “if” sākums
    …
  }
}

Ir svarīgi arī izvairīties no vietējām deklarācijām, kurās slēptas augstākā līmeņa deklarācijas, un izvairīties no neskaidrībām, kā parādīts zemāk

int skaits;
...
public void doSomething () {
  ja (nosacījums) {
    int skaits; // IZVAIRĪTIES!
    ...
  }
  ...
}

Atstarpes un līniju pārtraukumi - izvairieties no kārdinājuma ietaupīt 1–2 koda rindas uz lasāmības rēķina. Šeit ir aprakstīta paraugprakse attiecībā uz atstarpēm un tukšām rindām (baltā atstarpe tomēr izmaina)

  • Viena (1) tukša rinda starp metodēm un pavasara izstrādātājiem iesaka divas (2) tukšas rindas aiz konstruktoriem, statiskā bloka, laukiem un iekšējās klases
  • Kosmosa spilventiņu operatori, t.i., izmantojiet int foo = a + b + 1; over int foo = a + b + 1;
  • Atdaliet visus bināros operatorus, izņemot “.” No operandiem, izmantojot atstarpi
  • Atvērts lencīte “{” parādās tās pašas rindas beigās kā deklarācijas paziņojums vai metode, un noslēdzošā lencīte “}” sāk līniju pats par sevi.
// Dod priekšroku () - atstarpe aiz vārda "kamēr" un pirms "("
kamēr (patiesa) {
  ...
}
// Izvairieties no (x) - Atšķirībā no augšas nav atstarpes
kamēr (patiesa) {
  ...
}
// Dod priekšroku () - nav atstarpes starp “doSomething” un “(“
public void doSomething () {
  ...
}
// Izvairieties no (x) - atšķirībā no augšējās vietas
public void doSomething () {
  ...
}
// Dod priekšroku () - pēc argumenta pievienojiet atstarpi
public void doSomething (int a, int b) {
  ...
}
// Dod priekšroku () - atstarpe starp operandu un operatoriem (t.i., +, =)
a + = c + d;
a = (a + b) / (c * d);
kamēr (d ++ = s ++) {
  n ++;
}

Dokumentācija un komentāri

Ir vērts pieminēt, ka gandrīz viss kods mainās visā tā darbības laikā, un būs reizes, kad jūs vai kāds mēģināsit noskaidrot, kas paredzēts sarežģītam koda blokam, metodei vai klasei, ja vien tas nav skaidri aprakstīts. Realitāte gandrīz vienmēr ir šāda

Dažreiz komentāri par sarežģītu koda, metodes, klases komplektu nedod nekādu vērtību vai kalpo tā mērķim. Parasti tas notiek, komentējot lietas labā.

Komentāri būtu jāizmanto, lai sniegtu koda pārskatus un sniegtu papildu informāciju, kas pašā kodā nav viegli pieejama. Sāksim. Ir divu veidu komentāri

Īstenošanas komentāri - ir domāti koda komentēšanai vai komentēšanai par noteiktu koda ieviešanu.

Dokumentācijas komentāri - ir domāti, lai aprakstītu koda specifikāciju no ieviešanas brīvas perspektīvas un lasītu izstrādātājiem, kuriem, iespējams, nav avota koda.

Komentāru biežums dažreiz atspoguļo sliktu koda kvalitāti. Kad jūtaties spiesti pievienot komentāru, apsveriet iespēju pārrakstīt kodu, lai tas būtu skaidrāks.

Ieviešanas veidi Komentāri

Ir četri (4) ieviešanas komentāru veidi, kā parādīts zemāk

  • Bloķēt komentāru - skatīt piemēru zemāk
  • Komentārs vienā rindā - kad komentārs nav garāks par rindu
  • Komentāru noslēgums - ļoti īss komentārs ir pārvietots uz labo galu
  • Rindas beigu komentārs - sākas komentārs, kas turpinās uz jaunās līnijas. Tas var komentēt pilnu līniju vai tikai daļēju rindu. To nevajadzētu izmantot vairākās rindās pēc kārtas teksta komentāriem; tomēr to var izmantot vairākās rindās pēc kārtas, lai komentētu koda sadaļas.
// Bloķēt komentāru
/ *
 * Lietojums: nodrošina failu, metožu, datu struktūru aprakstu
 * un algoritmi. Var izmantot katra faila sākumā un
 * pirms katras metodes. Izmanto gariem komentāriem, kas neatbilst a
 * viena rinda. 1 Tukša rinda, lai turpinātu pēc bloķēšanas komentāra.
 * /
// Komentārs vienā rindā
ja (nosacījums) {
 / * Rīkoties ar stāvokli. * /
  ...
}
// Pabeigšanas komentārs
ja (a == 2) {
 atgriezties PATIESAM; /* īpašs gadījums */
} cits {
 atgriešanās isPrime (a); / * darbojas tikai nepāra a * /
}
// Rindas beigu komentārs
if (foo> 1) {
  // Veiciet dubultklikšķi.
  ...
} cits {
  atgriezties nepatiess; // Paskaidrojiet, kāpēc šeit.
}
// if (josla> 1) {
//
// // Veiciet trīskāršu darbību.
// ...
//}
// cits
// atgriezt nepatiesu;

Dokumentācijas komentāri (t.i., Javadoc)

Javadoc ir rīks, kas ģenerē HTML dokumentāciju no jūsu java koda, izmantojot komentārus, kas sākas ar / ** un beidzas ar * / - lai iegūtu sīkāku informāciju par Javadoc darbību vai vienkārši lasītu, skatiet Wikipedia.

Šeit ir Javadoc piemērs

/ **
 * Tiek atgriezts objekts Image, kuru pēc tam var uzkrāsot uz ekrāna.
 * URL argumentā ir jānorāda absolūts {@link URL}. Vārds
 * arguments ir specifikācija, kas ir relatīva ar URL argumentu.
 * 

 * Šī metode vienmēr atgriežas nekavējoties, neatkarīgi no tā, vai  * attēls pastāv. Kad šī sīklietotne mēģina uzzīmēt attēlu  * ekrāns, dati tiks ielādēti. Grafikas primitīvas  *, kas zīmē attēlu, ekrānā pakāpeniski krāsosies.  *  * @param url ir absolūts URL, kurā norādīta attēla bāzes vieta  * @param nosauc attēla atrašanās vietu attiecībā pret URL argumentu  * @atgrieziet attēlu norādītajā URL  * @skatiet attēlu  * /  publisks attēls getImage (URL URL, virknes nosaukums) {         izmēģiniet {             return getImage (jauns URL (URL, nosaukums));         } nozveja (MalformedURLException e) {             atgriezt null;         }  }

Un iepriekšminētais radītu HTML, kas izriet no tā, ja javadoc tiek palaists pret kodu, kuram ir iepriekš minētais

Skatīt šeit vairāk

Šeit ir daži galvenie tagi, kurus varat izmantot, lai uzlabotu ģenerētās java dokumentācijas kvalitāti.

@author => @author Raf
@code => {@code A  C}
@deprecated => @depreposed novecošanās ziņojums
@exception => @exception IOException tiek izmests, kad
@link => {@link package.class # member label}
@param => @param parametra nosaukuma apraksts
@return => Kāda metode atgriežas
@see => @see "string" VAI @see  
@since => Lai norādītu versiju, kad tiek pievienota publiski pieejama metode

Pilnu sarakstu un sīkāku aprakstu skatiet šeit

Twitter kodēšanas standartā nav ieteicams izmantot atzīmi @author

Kods savas dzīves laikā var mainīt īpašnieku vairākas reizes, un diezgan bieži sākotnējam avota faila autoram nav nozīmes pēc vairākām iterācijām. Mēs uzskatām, ka ir labāk uzticēties saistību vēsturei un OWNERS failiem, lai noteiktu koda kopuma īpašumtiesības.

Tālāk ir sniegti piemēri, kā jūs varētu uzrakstīt ieskatāmu dokumentācijas komentāru, kā aprakstīts Twitter kodēšanas standartā

// Slikti.
// - Dokumentā nekas nav teikts, ka metodes deklarācijā nebija.
// - Šis ir “pildījuma dokuments”. Tas izturētu stila pārbaudi, bet
nepalīdz nevienam.
/ **
 * Sadala virkni.
 *
 * @param s A virkne.
 * @return Stīgu saraksts.
 * /
Saraksts  split (stīgas);
// Labāk.
// - Mēs zinām, ko metode sadala.
// - Joprojām kaut kāda nenoteikta uzvedība.
/ **
 * Sadala virkni starp atstarpi.
 *
 * @param s Sadalāmā virkne {@Code null} virkne tiek uzskatīta par tukšu virkni.
 * @return Ievades daļu, kas nodalītas ar atstarpi, saraksts.
 * /
Saraksts  split (stīgas);
// Lieliski.
// - Aptver vēl vienu malu lietu.
/ **
 * Sadala virkni starp atstarpi. Atkārtotas atstarpes
 * ir sabrukuši.
 *
 * @param s Sadalāmā virkne {@Code null} virkne tiek uzskatīta par tukšu virkni.
 * @return Ievades daļu, kas nodalītas ar atstarpi, saraksts.
 * /
Saraksts  split (stīgas);

Rakstot komentārus, ir svarīgi būt profesionālam

// Izvairieties (x)
// Es tik ļoti ienīstu xml / ziepes, kāpēc tas nevar to izdarīt manis labā?
izmēģiniet {
  userId = Integer.parseInt (xml.getField ("id"));
} nozveja (NumberFormatException e) {
  ...
}
// Dod priekšroku ()
// TODO (Jim): bibliotēkas validācijas pārbaude bibliotēkā.
izmēģiniet {
  userId = Integer.parseInt (xml.getField ("id"));
} nozveja (NumberFormatException e) {
  ...
}

Ir svarīgi paturēt prātā, ka nav jādokumentē ignorētā metode, ja vien ieviešana nav mainījusies.

Un šeit ir vēl daži punkti, kas jāpatur prātā

  • Izvairieties no aizstājējzīmju importa - kā aprakstīts Twitter kodēšanas standartos, tas klases avotu padara mazāk skaidru. Es strādāju komandā, kurā ir dažādi Eclipse un IntelliJ lietotāji, un es uzzināju, ka Eclipse novērš aizstājējzīmju importu un IntelliJ to ievieš. Droši vien ir iespēja to izslēgt, vienkārši gribējās norādīt uz noklusējumu abiem.
  • Pārliecinoties vienmēr, izmantojiet @Override anotāciju
  • Veiciniet @Nullable izmantošanu, ja lauks vai metode parāda nulli
  • Izmantojiet īpašus komentārus turpmākajam darbam un neaizmirstiet atstāt atsauci uz sevi, lai citi zinātu, kam uzdot viņu Y jautājumu, nevis uzminēt, noņemt to vai pārbaudīt git vainu, lai atrastu, kurš to pievienoja. Daži IDE, piemēram, Eclipse un IntelliJ, arī palīdz uzskaitīt tos ērtai piekļuvei, kā arī atgādinājumu.
// FIXME (Raf): rīcībā esošs ziņojums apraksta to, kas jādara
// TODO (Raf): rīcībā esošs ziņojums apraksta to, kas jādara

Beigu spēle ir rakstīt kodu, kas atvieglo nākamo autoru un uzturētāju dzīvi.

Beigu spēle

Citi attiecīgie lasāmmateriāli

Atbilstošu rakstu saraksts, kas attiecas uz tīru, labi strukturētu, viegli lasāmu un uzturējamu kodu rakstīšanu. Ja vēlaties lasīt vairāk, noteikti iesakiet sekojošo

un vēl viens labs padoms tīra koda rakstīšanai