Java kódolási konvenciók

Miért van szükség kódolási konvenciókra? ~80% karbantartás több emberi erőforrás olvashatóság, érthetőség forráskód közzététele

Java forrásfájlok .java illetve .class kiterjesztések ~2000 programsor tartalmaz publikus osztályt vagy interfészt Tartalmazási sorrend: Kezdő megjegyzések Csomag-, importdeklarációk Osztály-, interfészdeklarációk

Kezdő megjegyzések /* * Osztálynév * * Verzióval kapcsolatos információk * Dátum * Copyright megjegyzések */

Csomag-, importdeklarációk első sor, mely nem megjegyzés: csomagdeklarációk utána import deklarációk példa: package csomag1.csomag2.csomag3; import javax.sound.midi.MidiChannel; import javax.sound.midi.MidiSystem; import javax.sound.midi.MidiUnavailableException; import javax.sound.midi.Synthesizer; vagy: import javax.sound.midi.*;

Osztály-, interfészdeklarációk (sorrend) Osztály- vagy interfészdeklaráció része Megjegyzések 1 Osztály/interfész dokumentációs megjegyzés (/** */) 2 Osztály/interfész fej 3 Osztály/interfész implementációs megjegyzések (ha szükséges) Tartalmazhat osztály vagy interfész szintű kiegészítő információkat, amelyek nem kerültek a dokumentációs megjegyzésbe. 4 Osztályváltozók Sorrend: nyilvános, protected, félnyilvános, privát 5 Példányváltozók Sorrend: u.a. 6 Konstruktorok 7 Metódusok Sorrend: működés alapján, olvashatóság, érthetőség

Behúzás, sorhossz behúzás alapegysége 4 szóköz karakter = 1 tab 80 karakterű sorhossz Sortörési alapelvek: vessző után operátor előtt magas szintű törések preferálása az alacsonyszintűekkel szemben új sor elhelyezése az előző sorban lévő azonos szintű kifejezés kezdetéhez igazítva ha a fenti szabályok a kód összezavarásához vezetnének, vagy a jobb margónál sűrűsödne -> kisebb behúzások

Behúzás, sorhossz (példa) peldaMetodus(hosszuKifejezes1, hosszuKifejezes2, hosszuKifejezes3); példa 2: valtozo = peldaMetodus1(hosszuKifejezes1, peldaMetodus2(hosszuKifejezes2, hosszuKifejezes3));

Aritmatikai kifejezéseken belüli sortörés (példa) longName1 = longName2 * (longName3 + longname4 - longName5) + 4 * longName6; // Ajánlott példa 2: longName1 = longName2 * (longName3 + longname4 - longName5) + 4 * longName6; // Kerülendő

Sortörés a feltételes kifejezésnél 1. //Ne használjuk ezt a behúzást if ((condition1 && condition2) || (condition3 && condition4) || (condition5 && condition6)){ doSomethingAboutIt(); } //Helyette így //Vagy így if ((condition1 && condition2) || (condition3 && condition4)

Sortörés a feltételes kifejezésnél 2. alpha = (aLongBooleanExpression) ? beta : gamma; alpha = (aLongBooleanExpression) ? beta : gamma; alpha = (aLongBooleanExpression) ? beta

Megjegyzések implementációs (//, /**/) dokumentációs (/** */) Célja: típusai: blokk, egysoros, utó-, sorvégi megjegyzés forráskód szövegének magyarázata dokumentációs (/** */) specifikáció magyarázata Célja: áttekintés nyújtás plusz információk ott ahol a kód nem egyértelmű segíti a megértést, áttekinthetőséget Hátrányok, kerülendő momentumok: redundáns adatok módosítása -> többletmunka könnyen elévülhet minőség <--> megjegyzés mennyisége

Implementációs megjegyzések 1. Blokk megjegyzések Használata: fájlok, metódusok, adatstruktúrák, algoritmusok leírása Példa: /* * Ez egy blokk megjegyzés */ Megjegyzés: kóddal azonos szinten kell lennie

Implementációs megjegyzések 2. Egysoros megjegyzések rövid azon a szinten amelyen az előző sor van előtte üres sor Példa: if (feltétel){ /* Ha a feltétel teljesül. */ ... }

Implementációs megjegyzések 3. Utómegjegyzések még rövidebb megjegyzések kóddal egy sorban, amit magyaráznak több esetén mind azonos távolságra Példa: if (a == 2){ return TRUE; /* speciális eset */ } else { return isPrime(a); /* csak páratlan számok esetén */ } Sorvégi megjegyzések (//) blokk megjegyzés egysoros megjegyzés utómegjegyzés

Dokumentációs megjegyzés Használata: osztályok, interfészek, metódusok, adattagok jellemzése Jellemzői: deklaráció előtt kell szerepelnie az itt megadottak megjelennek a dokumentációban

Dokumentációs megjegyzés (példa) /** * Dokumentáció szövege * * @param szam miért kell a "szam" bemenet * @param szoveg miért kell a "szoveg" bemenet * @return a visszatérési érték mit ad vissza */ public boolean valami(int szam, String szoveg){ ... }

Deklarációk Helye: lehetőleg az adott blokk elején kivétel a for ciklus Ajánlott: int level; //szint int size; //tábla mérete vagy int level; //szint int size; //tábla mérete Object entry; //bejegyzés Kerülendő: int level, size; Inicializálás ahol deklaráltuk, kivéve ha egy számítás eredménye lesz az értéke

Osztály, interfész deklarációk metódus név és paraméterlista között ne legyen szóköz metódus fejével egy sorba kerüljön a nyitó ("{") zárójel a záró ("}") zárójel mindig egymagában új sorban legyen (kivétel üres törzs esetén) metódusok üres sorral legyenek elválasztva egymástól Utasítások egyszerű utasítások: egy utasítás egy sor összetett utasítás: közrefogott utasítások egy szinttel beljebb nyitó zárójel a sor végén, záró zárójel új sorban, sor elején, annyival behúzva mint a kezdő utasítás

Üres sorok, szóközök használata üres sorokkal a logikailag összetartozó részeket emelhetjük ki két üres sor: osztály és interfész definíciók között egy üres sor: metódusok egy adott metódus lokális változói és első utasítás között blokk vagy egysoros megjegyzés előtt vagy egy metóduson belül az egyes logikai szakaszok között, olvashatóság érdekében Szóközök használata: ha az adott kulcsszót zárójel követi (kivéve metódusnál) argumentum listában minden kétoperandusú operátort (kivétel a . operátor) pl.: a += c + d; System.out.println("Valami " + a + "valami kettő"); kifejezéseket egy for utasításban típuskényszerítéseket szóköznek kell követnie pl.: a = (double) b / c;

Elnevezési konvenciók Azonosító típus Az elnevezés szabályai Példák Csomagok ASCII karakterekkel kell írni, top-level domain nevek egyikének kell lennie. (com, edu, net, org, stb.) A többi komponens egyre szűkíti a kört. com.sun.eng Osztályok Főnév, belső szavak első betűi nagyok. Egyszerű, kifejező, ne legyen rövidítés class ImageSprite Interfészek Osztályhoz hasonló interface Valami Metódusok Kisbetűvel keződő ige, belső szavak nagybetűvel kezdődnek runFast()

Azonosító típus Az elnevezés szabályai Példák Változók Kisbetűvel kezdődik, de nem lehet _ vagy $, a belső szavak nagybetűvel kezdődjenek. Legyen beszédes, de rövid. int i; char c; float myWidth; Konstansok Csupa ANSI nagybetű, szavak elválasztása _-al static final int MIN_WIDTH = 4;

Áttekintés (példa)

Köszönöm a figyelmet!