GeoSoft - Java Programming Style Guidelines

9 min

DepSeek prevod Java Programming Style Guidelines sa sajta https://geosoft.no/javastyle.html Ovde je 30 zapovesti od ukupno 97 - samo ono što se odnosi na Naming.

1. Imena koja predstavljaju pakete pišu se isključivo malim slovima.

mypackage, com.company.application.ui

Konvencija imenovanja paketa koja se koristi u osnovnim paketima Jave. Početni naziv paketa koji predstavlja naziv domena mora biti malim slovima.

2. Imena koja predstavljaju tipove (types) moraju biti imenice napisana u PascalCase.

Line, AudioSystem

Uobičajena praksa u razvojnoj zajednici Jave i takođe konvencija imenovanja tipova koja se koristi u osnovnim paketima Jave.

3. Imena promenljivih (varijabli) moraju biti u camelCase.

line, audioSystem

Uobičajena praksa u razvojnoj zajednici Jave i takođe konvencija imenovanja promenljivih koja se koristi u osnovnim paketima Jave. Olakšava razlikovanje promenljivih od tipova i efikasno rešava potencijalni sukob imenovanja kao u deklaraciji

Line line;

4. Imena koja predstavljaju konstante (Static final konstante) pišu se velikim slovima u formatu SCREAMING_SNAKE_CASE.

MAX_ITERATIONS, COLOR_RED

Uobičajena praksa u razvojnoj zajednici Jave i takođe konvencija imenovanja koja se koristi u osnovnim paketima Jave.

Generalno, upotreba takvih konstanti treba da bude svedena na minimum.

5. Imena koja predstavljaju metode - glagol ili glagolska fraza u formatu camelCase.

getName(), computeTotalWidth()

Uobičajena praksa u razvojnoj zajednici Jave i takođe konvencija imenovanja koja se koristi u osnovnim paketima Jave. Ovo je identično imenovanju promenljivih, ali metode u Javi se već mogu razlikovati od promenljivih po njihovom specifičnom obliku.

6. Skraćenice i akronime ne treba pisati velikim slovima kada se koriste kao ime.

exportHtmlSource(); // Pogrešno: exportHTMLSource();

readJsonFile(); // Pogrešno: readJSONFile();

Korišćenje svih velikih slova za osnovni naziv će dovesti do sukoba sa gore navedenim konvencijama imenovanja. Promenljiva ovog tipa bi morala da se zove `jSON`, `hTML` itd., što očigledno nije veoma čitko. Još jedan problem je ilustrovan u gornjim primerima: kada je ime povezano sa drugim, čitkost je ozbiljno smanjena. Reč koja sledi nakon akronima ne ističe se kao što bi trebalo.

7. Privatni članovi klase treba da imaju sufiks donje crte.

class Person

{

  private String name_;

  :

}

Osim svog imena i tipa, opseg člana je njegova najvažnija karakteristika. Označavanje opsega klase korišćenjem donje crte olakšava razlikovanje članova klase od lokalnih privremenih promenljivih. Ovo je važno jer se članovi smatraju značajnijim od argumenata metoda i promenljivih i programer bi trebalo da im posvećuje posebnu pažnju.

Nus-pojava konvencije imenovanja sa donjom crtom je to što lepo rešava problem pronalaženja razumnih imena promenljivih za setter metode:

  void setName(String name)

  {

    name_ = name;

  }

Pitanje je da li donja crta treba da bude dodata kao prefiks ili kao sufiks. Obe prakse su uobičajene, ali se preporučuje druga jer najbolje održava čitkost imena.

Treba napomenuti da je identifikacija opsega u promenljivima bila kontroverzna. Međutim, praksa je dobila široko prihvatanje u profesionalnoj razvojnoj zajednici.

8. Generičke promenljive treba da imaju isto ime kao njihov tip.

void setTopic(Topic topic) // Pogrešno: void setTopic(Topic value)

                           // Pogrešno: void setTopic(Topic aTopic)

                           // Pogrešno: void setTopic(Topic t)

void connect(Database database) // Pogrešno: void connect(Database db)
                                // Pogrešno: void connect(Database postgresDB)

Smanjuje složenost smanjenjem broja korišćenih pojmova i imena. Takođe olakšava zaključivanje tipa na osnovu samo imena promenljive. Ako iz nekog razloga ova konvencija ne izgleda prikladna, to je jak pokazatelj da je ime tipa loše izabrano.

Ne-generičke promenljive imaju ulogu. Ove promenljive se često mogu nazvati kombinovanjem uloge i tipa:

  Point  startingPoint, centerPoint;
  Name   loginName;

9. Svi nazivi moraju biti na engleskom.

Korišćenje engleskog za imena pojednostavljuje globalnu saradnju, obezbeđuje doslednost između sistema, pojednostavljuje proces uključivanja novih članova, obezbeđuje održavanje i održava tehnički žargon.

10. Promenljive sa velikim opsegom treba da imaju duga imena, promenljive sa malim opsegom mogu imati kratka imena.

Privremene promenljive koje se koriste za privremeno skladištenje ili indekse najbolje je držati kratkim. Programer koji čita takve promenljive treba da može da pretpostavi da se njena vrednost ne koristi van nekoliko linija koda. Uobičajene privremene promenljive za cele brojeve su `i`, `j`, `k`, `m`, `n` a za karaktere `c` i `d`.

11. Ime objekta je implicitno i treba ga izbegavati u nazivu metode.

line.getLength(); // Pogrešno: line.getLineLength();

Ovo drugo može izgledati prirodno u deklaraciji klase, ali se u upotrebi pokazalo suvišnim, kao što je prikazano u primeru.

12. Termini get/set moraju se koristiti gde se atributu direktno pristupa.

employee.getName();
employee.setName(name);

matrix.getElement(2, 4);
matrix.setElement(2, 4, value);

Uobičajena praksa u Java zajednici i konvencija koja se koristi u osnovnim paketima Jave.

13. is- prefiks treba koristiti za logičke (boolean) promenljive i metode.

isSet, isVisible, isFinished, isFound, isOpen

Ovo je konvencija imenovanja za logičke metode i promenljive koja se koristi u osnovnim paketima Jave. Korišćenje is- prefiksa rešava uobičajeni problem odabira loših logičkih imena kao što su status ili flag. isStatus ili isFlag jednostavno ne odgovara, i programer je primoran da izabere smislenija imena.

Setter metode za logičke promenljive moraju imati set- prefiks kao u:

void setFound(boolean isFound);

Postoji nekoliko alternativa is- prefiksu koje bolje odgovaraju u nekim situacijama. To su has-, can- i should- prefiksi:

boolean hasLicense();
boolean canEvaluate();
boolean shouldAbort = false;

14. Termin compute može se koristiti u metodima gde se nešto izračunava.

valueSet.computeAverage();
matrix.computeInverse();

Daje čitaocu odmah naznaku da je ovo potencijalno dugotrajna operacija, i ako se koristi ponavljano, on može razmotriti keširanje rezultata. Dosledna upotreba termina poboljšava čitkost.

15. Termin find može se koristiti u metodima gde se nešto traži.

vertex.findNearestVertex();
matrix.findSmallestElement();
node.findShortestPath(Node destinationNode);

Daje čitaocu odmah naznaku da je ovo jednostavna metoda pretrage sa minimumom proračuna. Dosledna upotreba termina poboljšava čitkost.

16. Termin initialize može se koristiti gde se uspostavlja objekat ili koncept.

document.initializeFontSet();

Američki oblik initialize treba da bude preferiran u odnosu na engleski initialise. Skraćenica init se mora izbeći.

17. Imena komponenti korisničkog interfejsa treba da imaju sufiks tipa elementa.

widthScale, nameTextField, leftScrollbar, mainPanel, fileToggle, minLabel, printerDialog

Poboljšava čitkost jer ime daje korisniku odmah naznaku tipa promenljive i time dostupnih resursa objekta.

18. Oblik množine treba koristiti za imena koja predstavljaju kolekciju objekata.

Collection<Point> points;
int[] values;

Poboljšava čitkost jer ime daje korisniku odmah naznaku tipa promenljive i operacija koje se mogu izvršiti na njenim elementima.

19. n- prefiks treba koristiti za promenljive koje predstavljaju više objekata.

nPoints, nTables

Ova notacija je preuzeta iz matematike gde je uspostavljena konvencija za označavanje broja objekata.

Imajte u vidu da se num prefiks koristi u osnovnim paketima Jave za ove promenljive. Ovo je verovatno trebalo da bude skraćenica za number of, ali pošto više liči na number to čini ime promenljive čudnim i pogrešnim. Ako je "number of" preferirani izraz, numberOf prefiks može se koristiti umesto samo n. num prefiks se ne sme koristiti.

20. Nikakav sufiks ne treba koristiti za promenljive koje predstavljaju broj entiteta.

tableNo, employeeNo

Ova notacija je preuzeta iz matematike gde je uspostavljena konvencija za označavanje broja entiteta.

Elegantna alternativa je da se takve promenljive prefiksuju sa i: iTable, iEmployee. Ovo ih efikasno čini imenovanim iteratorima.

21. Promenljive iteratora treba nazvati `i`, `j`, `k` itd.

for (Iterator i = points.iterator(); i.hasNext()) {

  :

}

for (int i = 0; i < nTables; i++) {

  :

}

Ova notacija je preuzeta iz matematike gde je uspostavljena konvencija za označavanje iteratora.

Promenljive imenovane `j`, `k` itd. treba koristiti samo za ugnežđene petlje.

22. Imena komplemenata moraju se koristiti za komplementarne entitete.

get/set, add/remove, create/destroy, start/stop, insert/delete,
increment/decrement, old/new, begin/end, first/last, up/down, min/max,
next/previous, open/close, show/hide, suspend/resume, etc.

Smanjuje složenost simetrijom.

23. Skraćenice u imenima treba izbegavati.

computeAverage(); // Pogrešno: compAvg();
ActionEvent event; // Pogrešno: ActionEvent e;
catch (Exception exception) { // Pogrešno: catch (Exception e) {

Postoje dve vrste reči za razmatranje. Prvo su uobičajene reči navedene u rečniku jezika. One se nikada ne smeju skraćivati. Nikada ne pišite:

cmd   umesto   command
comp  umesto   compute
cp    umesto   copy
e     umesto   exception
init  umesto   initialize
pt    umesto   point
itd.

Zatim postoje fraze specifične za domen koje su prirodnije poznate kroz svoje akronime ili skraćenice. Ove fraze treba držati skraćenim. Nikada ne pišite:

HypertextMarkupLanguage  umesto   html
CentralProcessingUnit    umesto   cpu
PriceEarningRatio        umesto   pe
itd.

24. Negirana imena logičkih promenljivih moraju se izbegavati.

bool isError; // Pogrešno: isNoError
bool isFound; // Pogrešno: isNotFound

Problem nastaje kada se koristi logički operator not i pojavi dvostruka negacija. Nije odmah očigledno šta !isNotError znači.

25. Povezane konstante (final promenljive) treba da imaju zajednički prefiks imena tipa.

final int COLOR_RED = 1;
final int COLOR_GREEN = 2;
final int COLOR_BLUE = 3;

Ovo ukazuje da konstante pripadaju zajedno i koji koncept konstante predstavljaju. Alternativa ovom pristupu je da se konstante stave u interfejs, efektivno prefiksujući njihova imena imenom interfejsa:

  interface Color

  {

    int RED   = 1;

    int GREEN = 2;

    int BLUE  = 3;

  }

26. Klase izuzetaka treba da imaju sufiks Exception.

class AccessException extends Exception

{

  :

}

Klase izuzetaka zaista nisu deo glavnog dizajna programa, i imenovanje ih na ovaj način ih ističe u odnosu na druge klase. Ovaj standard se koristi u osnovnim paketima Jave.

27. Podrazumevane implementacije interfejsa mogu se prefiksovati sa Default.

class DefaultTableCellRenderer

  implements TableCellRenderer

{

  :

}

Nije neuobičajeno kreirati jednostavnu klasnu implementaciju interfejsa koja pruža podrazumevano ponašanje za metode interfejsa. Konvencija prefiksovanja ovih klasa sa Default je usvojena od strane osnovnih paketa Jave.

28. Singleton klase treba da vraćaju svoju jedinu instancu kroz metodu getInstance.

public final class UnitManager

{

  private final static UnitManager instance_ = new UnitManager();

  private UnitManager()

  {

    :

  }

  public static UnitManager getInstance()  // NOT: get() or instance() or unitManager() etc.

  {

    return instance_;

  }

}

Uobičajena praksa u Java zajednici, mada je jezgro Jave paketa ne primenjuje dosledno. Gornji raspored je preporučeni šablon.

29. Klase koje kreiraju instance u ime drugih (fabrike) to mogu učiniti kroz metodu new[ClassName]

public class PointFactory

{

  public Point newPoint(...)

  {

    ...

  }

}

Ukazuje da je instanca kreirana pomoću new unutar fabričke metode i da je konstrukt kontrolisana zamena za new Point().

30. Funkcije (metode koje vraćaju objekat) treba imenovati prema onome što vraćaju, a procedure (void metode) prema onome što rade.

Povećava čitkost. Čini jasnim šta jedinica treba da uradi, a posebno sve stvari koje ne bi trebalo da uradi. Ovo opet olakšava održavanje koda čistim od nuspojava.