O konvencích

vložil Radek Červinka 12. ledna 2012 20:50

Je mi jasné, že s následujícím nebude hodně lidí souhlasit, ale je to jen moje zkušenost a nemusíte samozřejmě souhlasit.

Dlouhým vývojem a ve spolupráci se spolupracovníky nyní používáme určité principy při pojmenovávání všeho možného. Zkusím je nastínit a vysvětlit proč mi to vyhovuje i když se to někdy odlišuje od oficiální konvenze Delphi. Jedná se o tři oblasti: komponenty, soubory a proměnné + metody.

Komponenty

Vždycky jsem měl problém vymýšlet názvy komponent, zvláště v případě kdy spolu souvisejí, jako např. label nad editorem a povolující checkbox, nebo tlačítko toolbaru, položka menu a TAction.

Toto jsem vyřešil jednoduše prefixem (většinou 3 znakovým), např. lblFile, edtFile, chkFile, btnFile, actFile, miFile atd. Výhodou je opravdu velká přehlednost, odstranění problému s názvy, dobrá podpora v CnPack (např. přiřazením nové položce TMenuItem se podle jména akce přejmenuje položka menu na mi…) atd. Formulář má u mne prefix frm.

 lblComment: TLabel;
 memComment: TMemo;
 btnComment: TButton;  

Jinak toto je celkem používaný způsob - viz. CnPack.

Soubory

Tady to je jednoduché. Moje souboru začínají písmenem u v případě že neobsahují formulář, f v případě formuláře a d v případě datamodulu. Je do jednak z důvodu rychlosti vyhledání souboru v IDE a druhak z hlediska přehlednosti - hned tuším kde mohu soubor použít.

CnPack

Proměnné a metody

Od komponent k proměnným je podle mne logický krok. Uznávám, že to je ale na diskuzi. Já používám jednoznakový prefix určující základní typ (i - integer nebo celočíselné typy, b - boolean, cr - currency, s - string, o - objekt) a maximálně jednopísmenný prefix určující kombinaci viditelnosti a druhu. A nemám rád velká písmena. A všechny identifikátory anglicky.

  private
    fiValue: Integer;
  protected
    fsComment: string;
  public
    iValue: Integer;
    property piValue: Integer read fiValue write mSetValue;
  private
    foForms: TDictionary<string, TFormPlaceInfo>;
    procedure mShowForm(t: TfrmBaseClass; iImageIndex: Integer; iMasterId: Integer = 0);
    function moActiveForm: TfrmBase;
    procedure mEnterColor(Sender: TWinControl);
    function msFormKey(iCatalog, iMasterId:Integer):string;
    procedure mProxyCommand(iCmd: Integer);
  public
    procedure gInvokeQueryStatus;
    function gbCheckInput:Boolean;
  end;

Podle mne je to přehlednější z hlediska porovnávání změn mezi verzí, je to čitelnější a lépe se v tom hledají podezřelá místa (mimo jiné proto, že jednoduše dokáži odlišit náš "podezřelý" kód).

procedure mTest(iValue:Integer);
var
  sPrint: string;
begin
  if pbMaximum then
    gPrint(iValue)
  else
    mbReCheck(iValue);
  sPrint := gsPrintEx(psValue);
end;

Když se na tento kód podívám, tak okamžitě, aniž bych o tom něco věděl je mi jasné co jsou proměnné třídy, co public nebo globální metody, kde se netestuje návratová hodnota, kde se pracuje s property (a tedy něco co se bude vykonávat při přiřazení a třeba by bylo vhodné zamezit opakovanému volání v cyklu) atd.

V žádném případě nechci někomu něco vnucovat. Každý ať si používá co chce.

Tagy: ,

Praxe

Komentáře

13.1.2012 15:00:19 #

Karel Janeček

Čau Radku, já bych zcela určitě souhlasil, neboť své dřevní projekty ještě v Turbo Pascalu jsem psal bez rozlišování velkých a malých písmen a proměnné jsem nazýval, jak mě napadlo. Po letech uznávám, že to bylo docela nepřehledné, byť se mi to tehdy zdálo v pořádku.
Časem se člověk poučí a zavede systém, který mu vyhovuje. I z toho důvodu jsem uvítal Code Formatting v DXE (ony byl již asi i v dřívějších verzích, ale přecházel jsem z D2007 a verze 2009 a 2010 jsem nepořizoval).
Zdraví KJ

Karel Janeček

18.1.2012 11:43:52 #

<z>

nejhorsi je, kdyz s timhle clovek nema zkusenosti, a po nakym roce s velkym projektem zjisti,
ze by tohle bylo i vhodne :D :D

<z>

18.1.2012 11:52:20 #

Radekc

To byl právě i můj případ a cíl tohoto článku. Taky jsem byl pionýrem slepých uliček :-D

Radekc

25.1.2012 0:01:14 #

Kaco

Ahoj Radku
Par zaujimavosti:
System pomenovavania ktory popisujes sa vola "Hungarian notation", pomenovany podla Charlesa Simonyi-ho (http://cs.wikipedia.org/wiki/Charles_Simonyi , otec ms office, kozmicky turista). Nasiel som aj na edn clanok http://edn.embarcadero.com/article/27983. Osobne si myslim, ze nazov premennej ma popisovat ucel nie typ. Pascal ma typovu kontrolu na vysokej urovni. Vynimka potvrdzujuca pravidlo su vymenovane typy.
Vyborny je clanok od Xaviera Pacheco a Steve Teixeira http://www.econos.de/delphi/cs.html pripadne podobny clanok na edn http://edn.embarcadero.com/article/10280#3.3

Drzim palce v Tvojej osvetovej cinnosti

Kaco

25.1.2012 10:54:23 #

JaroB

Názvové konvence jsou jen způsob jak zpřehlednit identifikaci čehokoliv – objektů, globálních/lokálních proměnných, formulářů, záznamů atp. Snah pojmenovávat a odlišovat typy prefixem (fXXX formulář, rXXXzáznam, vXXX proměnná, gXXX globální proměnná, cXXX pravá konstanta) nemusí být zas tak od věci, ale je to to úplně nejobecnější pojmenovávání. Ovšem v případě podnikových systémů bývají kritická místa brány do aplikací ve formě export-import dat, publikace na web/html dokumentace nebo tiskové výstupy (xml). Jsou to místa, kdy vnitřní názvy např. globálních proměnných nebo objektů a jejich metod vybublají na povrch a jsou náhle veřejné.
Setkal jsem se s praxí, kdy se v těchto případech zakrývá vnitřní jméno nějakým dočasným, generovaným, nebo se používá indexování metod (ale oprava je při nějaké další změně extrémně pracná, pokud se takto musí spravit několik tisíc objektů nebo záznamů). Je to pracné, chybové, a chtějí to bezpečnostní útvary.
Vyvaroval bych se ale samoúčelnému označování jednoduchých typů (ale někdo to dělá) např. iCount – integer, bResult – boolean, dCoordX – double, sFilename – string atp. Překladač to správně typově ověří a vývojář se může vždycky kliknutím v deklaraci přesvědčit, o jaký typ se jedná. Něco jiného je to v JavaScriptu, tam si asi nemůžeme být jisti ničím, ale v Delphi? To spíš budeme víc zmateni API Windows a jejich obskurními popiskami.
A teď něco k vlastním identifikátorům (pozor, tady jde už o obsah, tj. co identifikátor popisuje a sděluje, ne o formu identifikátoru).
Je samozřejmě možné používat české resp. „ceske“ popisné identifikátory. V národním prostředí proti tomu nic nemám. Ale setkal jsem se kdysi s revizí zdrojového kódu (tuším hra <b>1848</b>), která měla kompletně všechno vnitřní názvosloví v maďarštině! No, to jsem opravdu nebyl chopen dokončit audit…to jen na okraj.
Trend, se kterým jsem se setkal, je že i na úrovni business logiky se používají kombinovaná anglická víceslovná jména a zkratková slova (např. cBusWarnLabel, vCntInvariant, gVertextHole, fReverseForm, rPolicyGermanFlow, vPRV == vPrimaryVertex atp.). V českém prostředí, kdy se vývojáři snaží vyhovět všem, dochází k absurdním situacím, kdy název je sice anglický, ale v originále neznamená nic nebo i něco jiného, protože je to čistý překlad/kalk českého názvu do angličtiny, ale tam je pro stejný název naprosto odlišný termín například viz „obmyšlená osoba“ = „beneficiary person“, přesněji „trust beneficiary person“; ovšem často je to překládané jako „fictive partner“ nebo dokonce „fuzzy person“ (což samozřejmě není správně). Obdobná situace je i v případě, že dodavatel sice nepochází z českého prostředí, ale není rodilý mluvčí, a tak pojmenuje podle svého identifikároty, které nejsou správně anglicky, ani je neleze správně přeložit do češtiny a ani neodpovídají jazyku rodilého mluvčího. Třeba když je dodavatel Ital, příkladem mohou být lavore (na cestě) x lavory (v kuchyni). Dodavatel prostě donese názvosloví a to se pak nějak vyvíjí a žije poměrně dlouhou dobu (dokonce v jedné mé aplikaci až dvanáct let, a to díky xml import/exportu).
Kromě prefixů jsem se setkal i s používáním postfixů, např. na jednoduché vygenerované webové stránce pět různých rodných čísel – ePersonInXXX, kde jako XXX byly použity číslice; To přestalo vyhovovat v okamžiku, když změny začaly provádět osoby poučené, které změnily číslice, protože se jim pletly, za jiné nečíselné identifikátory (ve výsledku byl bordel, resp. souběžné přežívání obou typů postfixů).
Prostě samotný identifikátor by běl být vždycky samopopisný, co nejunikátnější napříč aplikací (pokud se jedná o globální identifikátor), tak jak to dovoluje systém nebo IDE.
A jen malá poznámka na konec. Od Delphi 2005 je možné pojmenovávat spoustu identifikátorů plně česky s diakritikou. Kapku problém je s ukládáním událostí OnXXX – ty by měly být vždy bez diakritiky, ale lokálním proměnným to zjevně nevadí (ale zase, budu-li předávat aplikaci do Indie, pak nevím, jak mě tam pochválí).

JaroB

Komentování ukončeno

Naše nabídka

MVP
Ing. Radek Červinka - Embarcadero MVP
profil na linkedin, Twitter:@delphicz

Nabízím placené poradenství a konzultace v oblasti programování a vývoje SW.
Dále nabízíme i vývoj speciálního software na zakázku.

Neváhejte nás kontaktovat (i ohledně reklamy).

love Delphi

O Delphi.cz

Delphi je moderní RAD nástroj podporující tvorbu nativních aplikací pro platformu Win32, Win64, Mac OSX, Linux a na iPhone a Android.

Delphi.cz je nezávislý portál pro uživatele Delphi. Portál není koncipován pro úplné začátečníky, i když i ti se zde nebudou nudit, ale spíše na programátory, kteří již něco znají a chtějí své znalosti dále rozvíjet a sledovat novinky.

Poslední komentáře

Comment RSS

Dle měsíců