Konvence při psaní zdrojového kódu

Ondřej Linhart       01.01.2008       C#, VB.NET, VB6/VBA       22120 zobrazení

Jak psát zdrojový kód tak, aby byl snadno čitelný pro všechny...

V tomto článku bych se chtěl věnovat poměrně vyhledávanému tématu konvencí při psaní zdrojového kódu. Jedná se o způsob, jakým vývojář zapisuje zdrojový kód tak, aby byl snadno čitelný a přehledný. Toto se uplatňuje hlavně v prostředí, kde na projektu pracuje více lidí vzájemně sdílejících zdrojové kódy, ale i při psaní svého vlastního programu který používáte jen vy sami. Tím že budete psát kód čitelně usnadníte práci sobě i svým kolegům při pozdějším luštění zdrojového kódu.

1. Velká a malá písmena v názvech

Existují dva základní způsoby zápisu: Pascal case a Camel case.

Pascal case je způsob zápisu známý z jazyka Pascal. Spočívá v použití velkého písmena v prvním a každém dalším slově názvu, např. BeginInvoke, GetFileName, atd.

Camel case spočívá v použití malého písmena v prvním a velkého písmena v každém dalším slově názvu, např. customerOrders, tempFileName, atd.

Dříve se používal ještě způsob Hungarian notation (Visual Basic 6.0), který k názvu přidával předponu podle datového typu (strName pro proměnnou typu String, btnOK pro ovládací prvek Button atd.), tento způsob se však již nedoporučuje.

Názvy pouze s velkými písmeny je doporučeno používat pouze ve zkratkách, příkladem budiž System.IO nebo WebUI.

2. Maximální doporučená délka názvu

Z důvodu dobré čitelnosti by název neměl přesahovat délku přibližně 20 znaků. Viděl jsem zdrojové kódy, kde název metody běžně přesahoval 40 znaků.

3. Volba názvu

Při volbě názvu se snažte co nejlépe vystihnout účel.

Vyvarujte se stejných názvů, jako jsou jmenné prostory v .NET Frameworku (System, Collections, atd.).

Vyvarujte se stejných názvů jako jsou klíčová slova v daném jazyce (v případě Visual Basicu např. Erase, Error, MyClass...). Sice to lze (proměnnou můžete pojmenovat např. [String] s použitím hranatých závorek) ale silně se to nedoporučuje.

4. Doporučené pojmenování programových elementů

4.1 Třídy

  • K pojmenování použijte podstatné jméno.
  • Použijte Pascal case.
  • Zkratky používejte s rozvahou.
  • Nepoužívejte předpony (předpona C před názvem třídy, např. CCustomer)
  • Nepoužívejte podtržítko (_).

4.2 Rozhraní

  • K pojmenování použijte podstatné jméno nebo přídavné jméno vyjadřující chování (např. IDisposable).
  • Použijte Pascal case.
  • Zkratky používejte s rozvahou.
  • Použijte předponu I.
  • Nepoužívejte podtržítko (_).

4.3 Atributy

  • Použijte Pascal case.
  • Zkratky používejte s rozvahou.
  • Za názvem použijte příponu Attribute (např. ObsoleteAttribute).
  • Nepoužívejte podtržítko (_).

4.4 Výčtové typy

  • Použijte Pascal case.
  • Zkratky používejte s rozvahou.
  • Za názvem nepoužívejte příponu Enum.
  • Použijte jednotné číslo pro název běžných výčtových typů, množné číslo pro název výčtového typu který je tvořený bitovými hodnotami.
  • Vždy použijte FlagsAttribute u výčtového typu tvořeného bitovými hodnotami.

4.5 Statické položky (Static Fields)

  • Použijte Pascal case.
  • K pojmenování použijte podstatné jméno.
  • Snažte se používat statické vlastnosti místo statických položek.

4.6 Parametry

  • Použijte Camel case.
  • Snažte se aby název parametru odpovídal významu.

4.7 Metody

  • Použijte Pascal case.
  • Použijte slovesa pro název metody (např. Compute, Start, atd.)

4.8 Vlastnosti

  • K pojmenování použijte podstatné jméno.
  • Použijte Pascal case.
  • Zvažte použití stejného názvu jako je datový typ (např. BackgroundColor typu Color, VIPCustomer typu Customer, atd.)

4.9 Události

  • Použijte Pascal case.
  • U delegátů obslužné metody použijte příponu EventHandler nebo Callback podle použití.
  • Vždy použijte parametry sender (zdroj události) a e (parametry události), u třídy představující parametry události použijte příponu EventArgs.
  • K pojmenování použijte sloveso (např. Clicked, Painting).

4.10 Jmenné prostory

  • Použijte Pascal case.
  • U krátkých zkratek (System.IO) lze používat velká písmena, u delších zkratek (HTML) se doporučuje Pascal case (Html).
  • Ideální název jmenného prostoru je Firma.Produkt.Oblast, např. Microsoft.VisualBasic.Compatibility.

Česky nebo anglicky?

Záleží asi na každém, jestli se rozhodne používat pro názvy české nebo anglické výrazy. Já i mí kolegové používáme vždy anglické názvy a rozhodně bych to doporučil všem.

Microsoft FxCop

Microsoft FxCop je profesionální nástroj, který slouží vývojářům k analýze jejich zdrojového kódu ve smyslu dodržování obecných standardů při kódování. Tento nástroj je stažitelný zdarma a doporučil bych ho každému ať už začátečníkovi, nebo zkušenému vývojáři. Vzhledem k tomu, že FxCop údajně používá i sama firma Microsoft, nelze pochybovat o kvalitě tohoto nástroje.

http://www.gotdotnet.com/Team/FxCop/ 

Seznam zdrojů:

http://msdn2.microsoft.com/en-us/library/xzf533w0(vs.71).aspx

http://msdn2.microsoft.com/en-us/library/ms229002.aspx

http://en.wikipedia.org/wiki/Naming_conventions_%28programming%29

 

hodnocení článku

4 bodů / 4 hlasů       Hodnotit mohou jen registrované uživatelé.

 

Mohlo by vás také zajímat

Práce s časovými pásmy a letním časem v aplikaci a databázi - díl 3.: DateTimeOffset v .NET Frameworku

DateTimeOffset je méně využívanou alternativou struktury DateTime v .NET Frameworku. Navíc dovoluje ukládat časové pásmo a pohodlně s ním pracovat.

Jednoduchý scheduler v .NETu

Asi to znáte – máte nějaký složitější systém na zpracování velkého objemu dat a čas od času potřebujete vykovat nějakou automatizovanou údržbu – typicky smazat všechny položky starší než několika dní. Možností, jak toho dosáhnout, je hodně. Snažil jsem se vymyslet něco jednoduchého a efektivního.

Jeden antipattern, který dokáže asynchronní programování pořádně znepříjemnit

 

 

Nový příspěvek

 

Je toto špatně

Chtěl bych se zeptat, je lepší toto:

class Trida
{
  private int _hodnota;

  public void NejakaMetoda(int hodnota)
  {
    _hodnota = hodnota;
  }
}

nebo toto:

class Trida
{
  private int hodnota;

  public void NejakaMetoda(int hodnota)
  {
    this.hodnota = hodnota;
  }
}

Často se setkávám s oběma způsoby. A přiznám se, že se mě ten první líbí víc...

Nebo jak je toto správně?

nahlásit spamnahlásit spam 0 odpovědětodpovědět

Podle oficiálních konvencí je správně druhá možnost, ale používají se obě.

Důvod je, aby šlo odlišit, co je field a co je proměnná / parametr. Někdo to řeší zase tak, že místo podtržítek před použitím fieldů píše vždy důsledně this.

Já nepoužívám ani jedno z toho - přijde mi to nadbytečné. Pokud člověk pojmenuje proměnné a fieldy dostatečně výstižně, tak míst, kde by došlo k pochybnostem, je minimum.

nahlásit spamnahlásit spam 0 odpovědětodpovědět

Děkuji za odpověď.

Mě se u druhé možnosti nelíbí, že pokud se použije this tam kde není potřeba upozorňuje VS, že je tam zbytečně. Když tam this jednou je a jindy není, tak je to matoucí. Příklad:

class Trida
{
  private int hodnota;
  private int pocet;
 
  public void NejakaMetoda(int hodnota)
  {
    this.hodnota = hodnota;
    pocet += hodnota;
  }
  // já vím je to nesmyslná třída, ale asi chápete o co mi jde
}

Pokud člověk pojmenuje proměnné a fieldy dostatečně výstižně..

Jak by to tedy mělo vypadat?

nahlásit spamnahlásit spam 0 odpovědětodpovědět

Diskuse: Konvence při psaní zdrojového kódu

Zajímalo by mě, proč to tak je... kdo to vymyslel, že to tak má být, ...

nahlásit spamnahlásit spam 1 / 1 odpovědětodpovědět

Jde o to, aby kód psaný v .NETu vypadal jednotně. V článku jsou popsané konvence, které použili vývojáři .NET Frameworku a je vhodné, aby je používali všichni, kteří v .NETu programují, aby se styl pojmenování vlastních funkcí pokud možno nelišil od stylu pojmenování funkcí vestavěných.

Můžete si samozřejmě vymyslet vlastní konvence a řídit se podle nich, ale budete nekompatibilní s okolním světem, což třeba vadí při práci v týmu. Hlavní ale je mít na pojmenování a psaní kódu nějaký systém (jakýkoliv) a používat ho jednotně alespoň v rámci jednoho konkrétního projektu. Neí nic nepřehlednějšího, než když je půlka věcí psána a pojmenována tak a druhá zase jinak.

nahlásit spamnahlásit spam 3 / 3 odpovědětodpovědět

Diskuse: Konvence při psaní zdrojového kódu

Zdravím,

chtěl bych se zeptat autora:

podléhá nějaké takovéto etice i pojmenovávání komponent?

nahlásit spamnahlásit spam 0 odpovědětodpovědět

Komponenty (ať už běžné ovládací prvky, UserControl nebo Component) jsou třídy - tudíž pro pojmenování použijte stejná pravidla jako pro třídy.

nahlásit spamnahlásit spam 0 odpovědětodpovědět

Diskuse: Konvence při psaní zdrojového kódu

Diky za clanek, je to celkem zajimave jak se to ma delat.

Osobne si myslim, ze je jedno jestli pouzijete Pascal case,Camel case nebo madarskou konvenci.

Hlavne kdyz to clovek pouziva v celem projektu a kdyz si stanovi na zacatku jasna pravidla.

Je hrozne cist po nekom zdrojovy kod a jasne vidite, kdy je promenna pouzita uz pri navrhu a je hezky pojmenovana a kdy tam dal promennou tak rikajic na posledni chvili a dal tam tri pismena ktere nic nerikaji.

Ja ted ctu knihu o profesionalnim vyvoji ve VBA (Office) z roku 2005 a tam pouzivaji madarskou konvenci jeste obohacenou o par drobnosti a musim rict ze je to logicke a dobre se to cte !!

Premek

PS: mimochodem taky pouzivam madarskou konvenci, jsem zvykly, okamzite vim o co jde a kdyz to clovek dela s rozmyslem neni co zkazit

nahlásit spamnahlásit spam 1 / 1 odpovědětodpovědět

Diskuse: Konvence při psaní zdrojového kódu

Jako amatér výhodu vidím právě v používání českých názvů (bez diakritiky). Jasně se tak odliší názvy mnou zvolené proti anglickým názvům patřícím vývojovému prostředku (nepředpokládám práci v mezinárodním týmu).

Proč se dnes nehodí zkratky prvků před jejich názvem, pokud je defaultní název změněn (Hungarian notation)? V kódu, kde si programátor pojmenuje prvky dle svého bez předpon, pak nikdo druhý nepozná, o jaký prvek jde.

nahlásit spamnahlásit spam 1 / 1 odpovědětodpovědět

Vidíte-li přínos v používání českých názvů, já vám to neberu.

Máte-li dostatečnou znalost angličtiny, nebude pro vás problém pojmenovat cokoliv dost srozumitelně a zároveň tak, aby to nekolidovalo s něčím v .NET Frameworku.

Díky pokročilému vývojovému prostředí a hlavně zdokonalené technologii IntelliSense se již dnes maďarská anotace nepoužívá. Můžete nahlédnout do kódu automaticky generovaného vývojovým prostředím, příkladům dodávaným s Visual Studiem, SDK pro .NET Framework i MSDN - nikde již tuto historickou konvenci nenajdete.

Pokud máte zájem, trpělivost a dostatečnou znalost angličtiny tak filozofickou úvahu na téma Hungarian Notation najdete na MSDN (všimněte si hlavně data 1999 a názvu Visual Studio 6.0):

http://msdn2.microsoft.com/en-us/library...

nahlásit spamnahlásit spam 0 odpovědětodpovědět

S těmi anglickými názvy je to ošemetné, viděl jsem mnoho zdrojových kódů s anglickými pojmenování, ale bohužel daní programátoři pořádně anglicky neuměli, takže ve výsledku tomu nerozuměl nikdo. Takže spíš bych řekl, že možná lepší dobré české názvy, než špatné anglické.

Já osobně používám vždy anglické názvy (akorát tady v článcích někdy ne, abych nemátl začátečníky, kteří anglicky třeba neumí).

Nejdůležtější je ale používat v celém projektu konvence stejné, ať jsou již jakékoliv. Když je část psaná takhle a druhá část jinak, nepracuje se s tím dobře.

nahlásit spamnahlásit spam 1 / 1 odpovědětodpovědět
                       
Nadpis:
Antispam: Komu se občas házejí perly?
Příspěvek bude publikován pod identitou   anonym.

Nyní zakládáte pod článkem nové diskusní vlákno.
Pokud chcete reagovat na jiný příspěvek, klikněte na tlačítko "Odpovědět" u některého diskusního příspěvku.

Nyní odpovídáte na příspěvek pod článkem. Nebo chcete raději založit nové vlákno?

 

  • Administrátoři si vyhrazují právo komentáře upravovat či mazat bez udání důvodu.
    Mazány budou zejména komentáře obsahující vulgarity nebo porušující pravidla publikování.
  • Pokud nejste zaregistrováni, Vaše IP adresa bude zveřejněna. Pokud s tímto nesouhlasíte, příspěvek neodesílejte.

přihlásit pomocí externího účtu

přihlásit pomocí jména a hesla

Uživatel:
Heslo:

zapomenuté heslo

 

založit nový uživatelský účet

zaregistrujte se

 
zavřít

Nahlásit spam

Opravdu chcete tento příspěvek nahlásit pro porušování pravidel fóra?

Nahlásit Zrušit

Chyba

zavřít

feedback