View source for GeoSoft - Java Programming Style Guidelines

{{abstract|min=9|txt=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'''.}}

__NOTOC__

<div class="zapovesti">
<h4>1. Imena koja predstavljaju pakete pišu se isključivo malim slovima.</h4>
<div class="zapovesti-kod">
mypackage, com.company.application.ui
</div>
Konvencija imenovanja paketa koja se koristi u osnovnim paketima Jave. Početni naziv paketa koji predstavlja naziv domena mora biti malim slovima.
</div>

<div class="zapovesti">
<h4>
2. Imena koja predstavljaju tipove (types) moraju biti imenice napisana u PascalCase.
</h4>
<div class="zapovesti-kod">
Line, AudioSystem
</div>
Uobičajena praksa u razvojnoj zajednici Jave i takođe konvencija imenovanja tipova koja se koristi u osnovnim paketima Jave.
</div>

<div class="zapovesti">
<h4>
3. Imena promenljivih (varijabli) moraju biti u camelCase.
</h4>
<div class="zapovesti-kod">
line, audioSystem
</div>
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<br>

<span class="monofont"> Line line;</span>
</div>

<div class="zapovesti">
<h4>
4. Imena koja predstavljaju konstante (Static final konstante) pišu se velikim slovima u formatu SCREAMING_SNAKE_CASE. 
</h4>
<div class="zapovesti-kod">
MAX_ITERATIONS, COLOR_RED
</div>
Uobičajena praksa u razvojnoj zajednici Jave i takođe konvencija imenovanja koja se koristi u osnovnim paketima Jave.<br>

Generalno, upotreba takvih konstanti treba da bude svedena na minimum.
</div>

<div class="zapovesti">
<h4>
5. Imena koja predstavljaju metode - glagol ili glagolska fraza u formatu camelCase.
</h4>
<div class="zapovesti-kod">
getName(), computeTotalWidth()
</div>
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.
</div>

<div class="zapovesti">
<h4>
6. Skraćenice i akronime ne treba pisati velikim slovima kada se koriste kao ime.
</h4>
<div class="zapovesti-kod">
exportHtmlSource();
// <span class="pogresno">Pogrešno: exportHTMLSource();</span><br>

readJsonFile();     // <span class="pogresno">Pogrešno: readJSONFile();</span>
</div>
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.
</div>

<div class="zapovesti">
<h4>
7. Privatni članovi klase treba da imaju sufiks donje crte. 
</h4>
<div class="zapovesti-kod">
class Person

{

  private String name_;

  :

}
</div>
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.
</div>

<div class="zapovesti">
<h4>
8. Generičke promenljive treba da imaju isto ime kao njihov tip.
</h4>
<div class="zapovesti-kod">

void setTopic(Topic topic) // <span class="pogresno"><nowiki>Pogrešno: void setTopic(Topic value)</nowiki></span>

                           // <span class="pogresno"><nowiki>Pogrešno: void setTopic(Topic aTopic)</nowiki></span>

                           // <span class="pogresno"><nowiki>Pogrešno: void setTopic(Topic t)</nowiki></span>

void connect(Database database) // <span class="pogresno"><nowiki>Pogrešno: void connect(Database db)</nowiki></span><br>
                                // <span class="pogresno"><nowiki>Pogrešno: void connect(Database postgresDB)</nowiki></span>


</div>
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: 
<div class="monofont">
  Point  startingPoint, centerPoint; <br>
  Name   loginName;
</div>
</div>

<div class="zapovesti">
<h4>9. Svi nazivi moraju biti na engleskom.</h4>

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.
</div>

<div class="zapovesti">
<h4>10. Promenljive sa velikim opsegom treba da imaju duga imena, promenljive sa malim opsegom mogu imati kratka imena.</h4>

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`.
</div>

<div class="zapovesti">
<h4>11. Ime objekta je implicitno i treba ga izbegavati u nazivu metode.</h4>
<div class="zapovesti-kod">
line.getLength();   // <span class="pogresno">Pogrešno: line.getLineLength();</span>
</div>
Ovo drugo može izgledati prirodno u deklaraciji klase, ali se u upotrebi pokazalo suvišnim, kao što je prikazano u primeru.
</div>

<div class="zapovesti">
<h4>12. Termini get/set moraju se koristiti gde se atributu direktno pristupa.</h4>
<div class="zapovesti-kod">
employee.getName();<br>
employee.setName(name);<br>

matrix.getElement(2, 4);<br>
matrix.setElement(2, 4, value);
</div>
Uobičajena praksa u Java zajednici i konvencija koja se koristi u osnovnim paketima Jave.
</div>

<div class="zapovesti">
<h4>13. is- prefiks treba koristiti za logičke (boolean) promenljive i metode.</h4>
<div class="zapovesti-kod">
isSet, isVisible, isFinished, isFound, isOpen
</div>
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''. <span class="monofont">isStatus</span> ili <span class="monofont">isFlag</span> jednostavno ne odgovara, i programer je primoran da izabere smislenija imena.

Setter metode za logičke promenljive moraju imati set- prefiks kao u:
<div class="monofont">
void setFound(boolean isFound);
</div>
Postoji nekoliko alternativa is- prefiksu koje bolje odgovaraju u nekim situacijama. To su has-, can- i should- prefiksi:
<div class="monofont">
boolean hasLicense();<br>
boolean canEvaluate();<br>
boolean shouldAbort = false;
</div>
</div>

<div class="zapovesti">
<h4>14. Termin ''compute'' može se koristiti u metodima gde se nešto izračunava.</h4>
<div class="zapovesti-kod">
valueSet.computeAverage();<br>
matrix.computeInverse();
</div>
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.
</div>

<div class="zapovesti">
<h4>15. Termin ''find'' može se koristiti u metodima gde se nešto traži.</h4>
<div class="zapovesti-kod">
vertex.findNearestVertex();<br>
matrix.findSmallestElement();<br>
node.findShortestPath(Node destinationNode);
</div>
Daje čitaocu odmah naznaku da je ovo jednostavna metoda pretrage sa minimumom proračuna. Dosledna upotreba termina poboljšava čitkost.
</div>

<div class="zapovesti">
<h4>16. Termin ''initialize'' može se koristiti gde se uspostavlja objekat ili koncept.</h4>
<div class="zapovesti-kod">
document.initializeFontSet();
</div>
Američki oblik ''initialize'' treba da bude preferiran u odnosu na engleski ''initialise''. Skraćenica ''init'' se mora izbeći.
</div>

<div class="zapovesti">
<h4>17. Imena komponenti korisničkog interfejsa treba da imaju sufiks tipa elementa.</h4>
<div class="zapovesti-kod">
widthScale, nameTextField, leftScrollbar, mainPanel, fileToggle, minLabel, printerDialog
</div>
Poboljšava čitkost jer ime daje korisniku odmah naznaku tipa promenljive i time dostupnih resursa objekta.
</div>

<div class="zapovesti">
<h4>18. Oblik množine treba koristiti za imena koja predstavljaju kolekciju objekata.</h4>
<div class="zapovesti-kod">
Collection<Point> points;<br>
int[] values;
</div>
Poboljšava čitkost jer ime daje korisniku odmah naznaku tipa promenljive i operacija koje se mogu izvršiti na njenim elementima.
</div>

<div class="zapovesti">
<h4>19. n- prefiks treba koristiti za promenljive koje predstavljaju više objekata.</h4>
<div class="zapovesti-kod">
nPoints, nTables
</div>
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.
</div>

<div class="zapovesti">
<h4>20. Nikakav sufiks ne treba koristiti za promenljive koje predstavljaju broj entiteta.</h4>
<div class="zapovesti-kod">
tableNo, employeeNo
</div>
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.
</div>

<div class="zapovesti">
<h4>21. Promenljive iteratora treba nazvati `i`, `j`, `k` itd.</h4>
<div class="zapovesti-kod">

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

  :

}

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

  :

}
</div>
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.
</div>

<div class="zapovesti">
<h4>22. Imena komplemenata moraju se koristiti za komplementarne entitete.</h4>
<div class="zapovesti-kod">
get/set, add/remove, create/destroy, start/stop, insert/delete,<br>
increment/decrement, old/new, begin/end, first/last, up/down, min/max,<br>
next/previous, open/close, show/hide, suspend/resume, etc.
</div>
Smanjuje složenost simetrijom.
</div>

<div class="zapovesti">
<h4>23. Skraćenice u imenima treba izbegavati.</h4>
<div class="zapovesti-kod">
computeAverage();               // <span class="pogresno">Pogrešno: compAvg();</span><br>
ActionEvent event;              // <span class="pogresno">Pogrešno: ActionEvent e;</span><br>
catch (Exception exception) {   // <span class="pogresno">Pogrešno: catch (Exception e) {</span>
</div>
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:<br>

<span class="monofont">
cmd   umesto   command<br>
comp  umesto   compute<br>
cp    umesto   copy<br>
e     umesto   exception<br>
init  umesto   initialize<br>
pt    umesto   point<br>
itd.<br>
</span>

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:<br>

<span class="monofont">
HypertextMarkupLanguage  umesto   html<br>
CentralProcessingUnit    umesto   cpu<br>
PriceEarningRatio        umesto   pe<br>
itd.
</span>
</div>

<div class="zapovesti">
<h4>24. Negirana imena logičkih promenljivih moraju se izbegavati. </h4>
<div class="zapovesti-kod">
bool isError; // <span class="pogresno">Pogrešno: isNoError</span><br>
bool isFound; // <span class="pogresno">Pogrešno: isNotFound</span>
</div>
Problem nastaje kada se koristi logički operator not i pojavi dvostruka negacija. Nije odmah očigledno šta <span class="monofont">!isNotError</span> znači.
</div>

<div class="zapovesti">
<h4>25. Povezane konstante (final promenljive) treba da imaju zajednički prefiks imena tipa.</h4>
<div class="zapovesti-kod">
final int COLOR_RED   = 1;<br>
final int COLOR_GREEN = 2;<br>
final int COLOR_BLUE  = 3;
</div>
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;

  }
</div>

<div class="zapovesti">
<h4>26. Klase izuzetaka treba da imaju sufiks ''Exception''. </h4>
<div class="zapovesti-kod">
class AccessException extends Exception

{

  :

}
</div>
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.
</div>

<div class="zapovesti">
<h4>27. Podrazumevane implementacije interfejsa mogu se prefiksovati sa ''Default''. </h4>
<div class="zapovesti-kod">
class DefaultTableCellRenderer

  implements TableCellRenderer

{

  :

}
</div>
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.
</div>

<div class="zapovesti">
<h4>28. Singleton klase treba da vraćaju svoju jedinu instancu kroz metodu ''getInstance''.</h4>
<div class="zapovesti-kod">
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_;

  }

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

<div class="zapovesti">
<h4>29. Klase koje kreiraju instance u ime drugih (fabrike) to mogu učiniti kroz metodu ''new[ClassName]''</h4>
<div class="zapovesti-kod">
public class PointFactory

{

  public Point newPoint(...)

  {

    ...

  }

}
</div>
Ukazuje da je instanca kreirana pomoću ''new'' unutar fabričke metode i da je konstrukt kontrolisana zamena za <span class="monofont">new Point()</span>.
</div>

<div class="zapovesti">
<h4>30. Funkcije (metode koje vraćaju objekat) treba imenovati prema onome što vraćaju, a procedure (void metode) prema onome što rade.</h4>
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.
</div>