Java kodeerimise parimate tavade lühikokkuvõte

põhinevad Oracle, Google, Twitter ja Spring Framework kodeerimisstandarditel

Selle artikli eesmärk on anda teile kiire kokkuvõte tehtud tööst ja see ei tähenda, teisisõnu, eelistamist ja vältimist, mis põhinevad selliste tehniliste hiiglaste nagu Oracle, Google, Twitter ja Spring Framework kodeerimisstandarditel.

Võib-olla nõustute mõne siin esitatud parima tavaga või ei saa sellega nõustuda. See on täiesti hea, kui mõni kodeerimisstandard on olemas.

Miks üldse kodeerida standardeid? Kui kasutate seda Google'il, on palju häid põhjuseid ja ma jätan teile järgmise illustratsiooni

Kodeerimisstandardite dokument võib olla pikk ja igav. Selle artikli kirss korjab bitti ja tükki Google'i, Oracle'i, Twitteri ja Kevade kodeerimise tavadest ning selle eesmärk on pakkuda teile hõlpsasti järgitavat ja vähem igavat tavade komplekti, mis muudavad teie koodi hõlpsasti loetavaks ja hooldatavaks.

Peaaegu alati liitute olemasoleva tarkvaraga töötavate meeskondadega ja on üsna hea võimalus, et enamik autoreid on lahkunud erinevatest projektidest või vahetanud neid, jättes teid luhtunud koodiosadega, mis panevad teid inimkonda kahtlema.

Mõelgem erinevate kodeerimisstandardite parimatele tavadele.

Java lähtefail

Java lähtefailide puhul peetakse parimateks tavadeks järgmist:

  • Lähtefaili pikkus on väiksem kui 2000 koodirida
  • Lähtefail on korraldatud koos dokumendikommentaari, paketi deklaratsiooniga, millele järgneb klassikommentaar, import on grupeeritud (staatiline viimane), klassi / liidese allkiri ja nii edasi, nagu allpool näidatud
pakett com.example.model;
/ **
 * Rakenduseta perspektiiv, mida arendajad peavad lugema
 * kellel ei pruugi tingimata olla lähtekoodi käepärast
 *
 * @author x, y, z
 * @kohting tüdruku või poisiga
 * @versioon
 * @ autoriõigused
 *
 * /
import com.example.util.FileUtil;
/ *
 * Valikuline klassikommentaar
 *
 * /
avalik klass SomeClass {
  // Staatilised muutujad nähtavuse järjekorras
  staatiline avalik täisarv PUBLIC_COUNT = 1;
  staatiline lõplik täisarv PROTECTED_COUNT = 1;
  privaatne staatiline lõplik täisarv PRIVATE_COUNT = 1;
  // Juhtumi muutujad nähtavuse järjekorras
  avalik keelpillinimi;
  String postiindeks;
  privaatne Stringi aadress;
  // Konstruktor ja ülekoormatud järjestikuses järjekorras
  avalik SomeClass () {}
  avalik SomeClass (stringinimi) {
    see.nimi = nimi;
  }
  // Meetodid
  avalik keel String doSomethingUseful () {
    tagasi "Midagi kasulikku";
  }
  // getters, setters, equals, hashCode ja toString lõpus
}

Nimetamine

Klasside ja liideste nimed on CamelCase ning soovitatav on kasutada kogu sõna ja vältida akronüümide / lühendite kasutamist. Näiteks klass Raster või klass ImageSprite

  • Pakett - nimed com.deepspace üle com.deepSpace või com.deep_space
  • Failinimed on CamelCase ja lõppevad klassi nimega .java. Faili kohta on üks avalik klass, iga failis on üks tipptasemel klass
  • Meetod - nimed peaksid olema tegusõnad segatud tähtedega, iga sisesõnaga kirjutatakse suurtähed, näiteks run (); või runFast ();
  • Konstandid - peaksid olema suured tähed, eraldades iga sõna näiteks _, näiteks int MIN_WIDTH = 44; ja int MAX_WIDTH = 99;
  • Muutuja - nimi, mis ütleb programmi lugejale, mida muutuja esindab, st kui salvestate testi hinde, siis valige hinne vs var1. Hoidke muutujate nimed lühikeseks, vältige metaandmete lisamist.
// Eelista () - muutujate nimed on lühikesed ja kirjeldage, mida see salvestab
int schoolId;
int [] filtersSchoolIds;
int [] uniqueSchooldIds;
Kaart  usersById;
Stringi väärtus;
// Välti (x) - muutujate liiga detailne nimetamine
int schoolIdentificationNumber;
int [] userProvidedSchoolIds;
int [] schoolIdsAfterRemovingDuplicates;
Kaart  idToUserMap;
Stringi väärtusString;

Pidage meeles - muutuja nimi peaks olema lühike ja andma lugejale kergesti teada, millist väärtust see esindab. Kasutage oma otsustusvõimet.

Eelista ja väldi

Vormindamine ja treppimine on seotud ainult teie koodi korraldamisega, et see oleks hõlpsasti loetav, ja see hõlmab vahed, rea pikkust, mähiseid ja katkeid jne.

  • Treppimine - kasutage 2 või 4 tühikut ja püsige ühtlane
  • Rea pikkus - kuni 70 kuni 120 tähemärki sõltuvalt loetavuse mõjust. Pärast koma ja operaatorit on oluline kaotada horisontaalne kerimine ja paigutada reavahetused.

Meetodid - siin on loetelu parimatest tavadest

// Eelista () Rea katkemine on meelevaldne ja katkeb pärast koma.
String downloadAnInternet (Internet Internet, Torud,
    Blogosfääri ajaveebid, Kogus  ribalaius) {
  tube.download (internet);
}
// Vältige (x) meetodit on raske diferentseerida meetodi korpusesse
String downloadAnInternet (Internet Internet, Torud,
    Blogosfääri ajaveebid, Kogus  ribalaius) {
    tube.download (internet);
}
// Eelista () Lisage sügava taande jaoks 8 (topelt 2 või 4) tühikut
privaatne staatiline sünkroniseeritud horkingLongMethodName (int anArg,
        Objekt elseArg, string veelAnotherArg,
        Object andStillAnother) {
  ...
}
// Eelista () Lihtne skaneerimine ja täiendav veeru ruum.
avalik stringi allalaadimineAnternetis (
    Internet Internet,
    Torud torud,
    Blogosfääri ajaveebid,
    Kogus  ribalaius) {
  tube.download (internet);
  ...
}
Ühikatse oleks selle caught saavutanud

If-check - IMO kirjutades hästi vormindatud koodi, on autori ja koodide ülevaatajatele kergem kirjavigu ja vigu märgata, vt allpool:

// Väldi (x) Ära jäta välja {}
kui (tingimus)
  avaldus;
// Väldi (x)
kui (x <0) negatiivne (x);
// Väldi (x)
if (a == b && c == d) {
...
}
// Eelista ()
if ((a == b) && (c == d)) {
...
}
// Eelista ()
if (tingimus) {
  avaldused;
} muidu kui (tingimus) {
  avaldused;
} muidu kui (tingimus) {
  avaldused;
}
// Väldi (x)
if ((tingimus1 && tingimus2)
    || (tingimus3 ja & tingimus4)
    ||! (tingimus5 && tingimus6)) {// BAD WRAPS
    doSomethingAboutIt (); // TEE SELLE LINNA LIHTSALT MUST
}
// Eelista ()
if ((tingimus1 && tingimus2)
        || (tingimus3 ja & tingimus4)
        ||! (tingimus5 && tingimus6)) {
    doSomethingAboutIt ();
}

Kolmekomponendi operaator - ja allpool on soovitatavad tavad

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

Lülita - kui on vaja minna, on see parim tava

  • Kasutage alati vaikekorda isegi ilma koodita
  • Kasutage nuppu * * langeb läbi * /, et näidata juhtimisseadme järgmise juhtumi langust
lüliti (tingimus) {
  juhtum ABC:
    avaldused;
  / * kukub läbi * /
  juhtum DEF:
    avaldused;
    vaheaeg;
  vaikimisi:
    avaldused;
     vaheaeg;
}

Erandteated - erandi tegemisel on siin heade ja halvasti sisselõigatud sõnumite näidised.

// Vältige (x) - pole kerge lugeda
looge uus IllegalStateException ("Taotluse töötlemine ebaõnnestus" + request.getId ()
    + "kasutaja jaoks" + kasutaja.getId () + "päring:" "+ päring.getText ()
    + "'");
// Eelista () - üsna hõlpsasti loetav
looge uus IllegalStateException ("töötlemine ebaõnnestus"
    + "päring" + päring.getId ()
    + "kasutaja jaoks" + user.getId ()
    + "päring:" "+ päring.getText () +" "");

Iteraatorid ja ojad - ojad muutuvad üha tavalisemaks ja mõnikord võivad need olla väga keerulised, et neid oleks kerge lugeda.

// Vältige (x) - pole kerge lugeda
Tühjendatavad  moodulid = ImmvableList.  builder (). Add (new LifecycleModule ())
    .add (uus AppLauncherModule ()). addAll (application.getModules ()). build ();
// Eelista () - üsna hõlpsasti loetav
Parandatavad  moodulid = ImmvableList.  ehitaja ()
    .add (uus elutsükli moodul ())
    .add (uus AppLauncherModule ())
    .addAll (application.getModules ())
    .build ();
Järgige lihtsalt kodeerimisstandardit - ükskõik mida

Deklaratsioonid ja ülesanded - soovitatav on üks deklaratsioon rea kohta, kuna see julgustab märkusi, nagu allpool näidatud.

// Eelista ()
int tase; // taande tase
int suurusMeter; // tabeli suurus
// Vältige (x) ülaltoodut
int tase, suurusMeter;
// Eelista () - lisage ühik muutuja nime või tüübi hulka
pikk küsitlusIntervalMs;
int fileSizeGb;
Kogus  failisuurus;
// Vältige (x) tüüpide segamist
int foo, fooarray [];
// Vältige (x) - ärge eraldage komaga
Formaat.print (System.out, “tõrge”), väljumine (1);
// Vältige (x) mitmekordset määramist
fooBar.fChar = barFoo.lchar = 'c';
// Vältige (x) manustatud ülesandeid, et parandada jõudlust // või rida salvestada. Olen selles süüdi :(
d = (a = b + c) + r;
// Eelista () ülevalpool
a = b + c;
d = a + r;
// Eelista ()
Keel [] args
// Väldi (x)
Keelpillid []
// Eelista () Kasutage pikka sõna "L" asemel "L", et mitte segi ajada 1-ga
pikk ajalõpp = 3000000000L;
// Vältige (x) - raske öelda, viimane täht on l ja mitte 1
pikk ajalõpp = 3000000000l;

Deklaratsioonid tuleb sisestada ainult lahtrite algusesse (plokk on ümbritsetud lokkis traksidega {ja}). Ärge oodake muutujate deklareerimist enne nende esimest kasutamist; see võib segadusse ajada programmeerija ja takistada koodi teisaldatavust selle ulatuse piires.

// Eelista () deklareeri bloki alguses.
avalik tühine doSomething () {
  mis on olemas; // meetodiploki algus
  if (tingimus) {
    int mõnedFlag; // ploki “if” algus
    …
  }
}

Samuti on oluline vältida kohalikke deklaratsioone, mis varjavad kõrgema astme deklaratsioone, ning vältida segadusi, nagu on näidatud allpool.

int arv;
...
avalik tühine doSomething () {
  if (tingimus) {
    int arv; // VÄLTIMA!
    ...
  }
  ...
}

Tühikud ja reavahetused - vältige kiusatust salvestada 1–2 koodirea loetavuse arvelt. Siin on kõik tühikute ja tühjade ridade vahetamise parimad tavad (tühik muudab midagi)

  • Üks (1) tühi rida meetodite ja kevadiste arendajate vahel soovitab konstruktorite, staatilise ploki, väljade ja siseklassi järel kaks (2) tühja rida
  • Tühikuklahvide operaatorid, st kasutage int foo = a + b + 1; üle int foo = a + b + 1;
  • Eraldage kõik binaarsed operaatorid, va “.”, Tühikutega operandidest
  • Deklaratsiooni või -meetodiga sama rea ​​lõppu ilmub lahtine traksidega „{” ja sulgeva traksidega „}” algab rida ise taandes
// Eelista () - tühik pärast sõna "samas" ja enne "("
kuigi (tõsi) {
  ...
}
// Vältige (x) - erinevalt ülalt pole tühikut
kuigi (tõsi) {
  ...
}
// Eelista () - tühikut "doSomething" ja "("
avalik tühine doSomething () {
  ...
}
// Vältige (x) - erinevalt tühikust
avalik tühine doSomething () {
  ...
}
// Eelista () - lisage tühik pärast argumenti
avalik tühine doSomething (int a, int b) {
  ...
}
// Eelista () - tühik operandi ja operaatorite vahel (st +, =)
a + = c + d;
a = (a + b) / (c * d);
samas (d ++ = s ++) {
  n ++;
}

Dokumentatsioon ja kommentaarid

Väärib märkimist, et peaaegu kogu kood muutub kogu selle eluea jooksul ja on kordi, kui teie või keegi proovib aru saada, mida keeruline koodiplokk, meetod või klass on ette nähtud, kui seda pole selgelt kirjeldatud. Tegelikkus on peaaegu alati järgmine

Mõnikord on keeruka kooditüki, meetodi, klassi kommentaar väärtust lisamata või eesmärki täitmata. See juhtub tavaliselt siis, kui seda kommenteeritakse.

Kommentaare tuleks kasutada koodide ülevaate saamiseks ja lisateabe saamiseks, mida koodil endal pole hõlpsasti saadaval. Alustame. Kommentaare on kahte tüüpi

Rakenduskommentaarid - on mõeldud koodi kommenteerimiseks või koodi konkreetse rakenduse kommenteerimiseks.

Dokumentatsiooni kommentaarid - on mõeldud koodi spetsifikatsiooni kirjeldamiseks ilma rakenduseta perspektiivist, et seda saaks lugeda arendajad, kellel ei pruugi tingimata olla lähtekoodi käepärast.

Kommentaaride sagedus kajastab mõnikord koodi halba kvaliteeti. Kui tunnete, et peate kommentaari lisama, kaaluge koodi selgemaks muutmist.

Rakendamise kommentaaride tüübid

Allpool on näidatud neli (4) rakenduskommentaari tüüpi

  • Blokeeri kommentaar - vaadake näidet allpool
  • Üherealine kommentaar - kui kommentaar ei ole pikem kui rida
  • Kommentaaride lõpp - väga lühike kommentaar on viidud õigesse otsa
  • Rea lõpu kommentaar - algab kommentaar, mis jätkub uuel real. See võib kommenteerida terve rea või ainult osalise rea. Seda ei tohiks teksti järjestikuste ridade jaoks kasutada; siiski saab seda kasutada järjestikuste mitme reana koodilõikude kommenteerimiseks.
// Blokeeri kommentaar
/ *
 * Kasutamine: kirjeldab faile, meetodeid, andmestruktuure
 * ja algoritmid. Saab kasutada iga faili alguses ja
 * enne iga meetodit. Kasutatakse pikkade kommentaaride jaoks, mis ei sobi a
 * üherealine. 1 Pärast blokeeritud kommentaari jätkamiseks tühi rida.
 * /
// Üherealine kommentaar
if (tingimus) {
 / * Hooldage seisukorda. * /
  ...
}
// Lõplik kommentaar
if (a == 2) {
 tagasi TÕESTI; /* erijuhtum */
} veel {
 tagastus onPrime (a); / * töötab ainult paaritu * korral
}
// rea lõpu kommentaar
if (foo> 1) {
  // Tehke topeltklapp.
  ...
} veel {
  tagastama vale; // Selgitage, miks siin.
}
// if (riba> 1) {
//
// // Tehke kolmikklapp.
// ...
//}
// muud
// tagasta vale;

Dokumentatsiooni kommentaarid (nt Javadoc)

Javadoc on tööriist, mis genereerib HTML-dokumendid teie java-koodist, kasutades kommentaare, mis algavad tähega / ** ja lõpevad tähega * / - Javoci toimimise kohta leiate lisateavet Vikipeediast või lugege seda lihtsalt.

Siin on näide Javadocist

/ **
 * Tagastab pildiobjekti, mille saab seejärel ekraanile maalida.
 * URL-i argument peab määrama absoluutse {@link URL}. Nimi
 * argument on urli argumendi suhtes täpsustaja.
 * 

 * See meetod naaseb alati kohe, sõltumata sellest, kas  * pilt on olemas. Kui see applet proovib pilti joonistada  * ekraan, andmed laaditakse. Graafika primitiivid  *, mis pilti joonistavad, värvub ekraanile järk-järgult.  *  * @param url on absoluutne URL, mis annab pildi lähtekoha  * @param nimetage pildi asukoht url-argumendi suhtes  * @pöörake pilti määratud URL-il  * @vaada pilti  * /  avaliku pildi saamine (URL-i URL, stringi nimi) {         proovige {             return getImage (uus URL (URL, nimi));         } saak (MalformedURLException e) {             tagasi null;         }  }

Ja ülalolev moodustaks HTML-i järgmiselt, kui javadoc juhitakse ülaltoodud koodi vastu

Vaata siit lähemalt

Siin on mõned võtmesildid, mida saate kasutada loodud java dokumentatsiooni kvaliteedi parandamiseks.

@author => @author Raf
@code => {@kood A  C}
@deprecated => @depreposed aegunud teade
@exception => @exception IOException visatakse millal
@link => {@link package.class # liikme silt}
@param => @param parameetri-nime kirjeldus
@return => Mida meetod tagastab
@ see => @ see "string" VÕI @ vaata  
@since => versiooni märkimiseks, kui lisatakse avalikult juurdepääsetav meetod

Täieliku loetelu ja täpsema kirjelduse leiate siit

Twitteri kodeerimisstandard soovitab @author märgendit mitte kasutada

Kood võib oma elu jooksul omanikke vahetada mitu korda ja üsna sageli pole lähtefaili algsel autoril pärast mitu iteratsiooni tähtsust. Koodide kogu omandiõiguse kindlakstegemiseks on parem usaldada ajalugu ja OWNERS-faile.

Järgnevalt on toodud näited selle kohta, kuidas saaksite kirjutada dokumentide kommentaari, mis on arusaadav, nagu on kirjeldatud Twitteri kodeerimisstandardis

// Halb.
// - Doc ei ütle midagi, mida meetodi deklaratsioon ei andnud.
// - See on 'täitedokument'. See läbiks stiilikontrolli, kuid
ei aita kedagi.
/ **
 * Poolitab stringi.
 *
 * @param s string.
 * @return stringide loend.
 * /
Loend  split (stringid);
// Parem.
// - Me teame, mis meetodil lõheneb.
// - ikkagi mingi määratlematu käitumine.
/ **
 * Jagab tühimiku stringi.
 *
 * @param s Jagatav string. Stringi {@code null} käsitletakse tühjana.
 * @return Sisendi tühimikuga piiratud osade loetelu.
 * /
Loend  split (stringid);
// Suurepärane.
// - hõlmab veel ühte servajuhtumit.
/ **
 * Jagab tühimiku stringi. Korduvad tühimärgid
 * on kokku ahendatud.
 *
 * @param s Jagatav string. Stringi {@code null} käsitletakse tühjana.
 * @return Sisendi tühimikuga piiratud osade loetelu.
 * /
Loend  split (stringid);

Kommentaaride kirjutamisel on oluline olla professionaalne

// Väldi (x)
// Ma vihkan nii palju xml / seepi, miks ei võiks see minu jaoks seda teha ??
proovige {
  userId = Integer.parseInt (xml.getField ("id"));
} saak (NumberFormatException e) {
  ...
}
// Eelista ()
// TODO (Jim): teegi välja valideerimine eemaldatakse.
proovige {
  userId = Integer.parseInt (xml.getField ("id"));
} saak (NumberFormatException e) {
  ...
}

Ja on oluline meeles pidada, et mitte dokumenteerida ülekirjutatud meetodit, kui rakendamine pole muutunud.

Ja siin on veel mõned punktid, mida tuleks meeles pidada

  • Vältige metamärkide importimist - nagu kirjeldatakse Twitteri kodeerimisstandardites, muudab see klassi allika vähem selgeks. Töötan meeskonnas, kus on Eclipse'i ja IntelliJi kasutajaid, ning sain teada, et Eclipse eemaldab metamärkide impordi ja IntelliJ tutvustab seda. Tõenäoliselt on võimalus see välja lülitada, tahtsin lihtsalt kahele vaikimisi välja tuua.
  • Kasutage alati ületamiseks märkust @Override
  • Julgustage @Nullable kasutamist, kui väli või meetod annab nulli
  • Kasutage edaspidise töö jaoks spetsiaalseid kommentaare ja ärge unustage, et jätke endale viide, nii et teised teaksid, kellele esitada Y-küsimus, selle asemel, et arvata, eemaldada või kontrollida oma süüd, et leida, kes selle lisas. Mõned IDE-d, näiteks Eclipse ja IntelliJ, aitavad neid hõlpsasti juurde pääseda ja meeldetuletust loetleda.
// FIXME (Raf): toiminguga sõnum kirjeldab, mida tuleb teha
// TODO (Raf): toiminguga sõnum kirjeldab, mida tuleb teha

Lõppmäng on kirjutada kood, mis teeb tulevaste autorite ja hooldajate elu lihtsaks.

Lõppmäng

Muud asjakohased lugemismaterjalid

Puhta, hästi struktureeritud, hõlpsasti loetava ja hooldatava koodi kirjutamiseks oluliste artiklite loetelu. Kui soovite rohkem lugeda, soovitage kindlasti järgmist

ja veel üks hea loetelu näpunäidetest puhta koodi kirjutamiseks