<page xmlns="http://projectmallard.org/1.0/" xmlns:its="http://www.w3.org/2005/11/its" type="topic" id="c-coding-style" xml:lang="cs">

  <info>

    <link type="guide" xref="index#general-guidelines"/>

    <credit type="author copyright">

      <name>Federico Mena-Quintero</name>

      <email its:translate="no">federico@gnome.org</email>

      <years>2013</years>

    </credit>

    <credit type="author copyright">

      <name>Tým GTK+</name>

    </credit>

    <include xmlns="http://www.w3.org/2001/XInclude" href="cc-by-sa-3-0.xml"/>

    <desc>Naše pokyny pro psaní kódu v jazyce C pro GNOME</desc>

  </info>

  <title>Styl psaní kódu v C</title>

  
Dokument ukazuje preferovaný styl psaní kódu pro programy v jazyce C v GNOME. Ačkoliv je styl psaní kódu hodně záležitostí osobního vkusu, v GNOME dáváme přednost stylu, který poskytne jednotnost, čitelnost a půjde dobře spravovat.

  
Ukážeme si příklady správného stylu kódu i příklady špatného stylu, který je v GNOME nepřijatelný. Snažte se prosím své příspěvky zasílat ve stylu, který GNOME vyhovuje. Dáte tím najevo, že jste svoji práci odvedli s úctou k cílům projektu, k nimž patří udržitelnost kódu. Takovéto příspěvky se také mnohem lépe kontrolují.

  <note>

    
Tento dokument se týká kódu v jazyce C. Na další jazyky se podívejte na <link xref="index">hlavní stránku</link> pokynů k programování v GNOME.

  </note>

  
Tato příručka je významně inspirována dokumenty GTK’s CODING-STYLE, Linux Kernel’s CodingStyle a GNU Coding Standards. Ty se od sebe navzájem lehce odlišují konkrétními úpravami pro konkrétní potřeby projektu a jeho kulturu, a verze pro GNOME v tom není výjimkou.

  <section id="most-important-rule">

    <title>Jednoduché nejdůležitější pravidlo</title>

    
Prosté a přitom nejdůležitější pravidlo při psaní kódu je: podívejte se na kód okolo a snažte se jej napodobit.

    
Správce bývá zděšen, když obdrží záplatu, která se vyloženě liší stylem kódování od okolního kódu. Je to bezohledné, jako když někdo vstoupí do uklizeného domu se zablácenými botami.

    
Takže to, co tento dokument doporučuje, je, abyste při psaní záplaty pro již existující kód, zachovali jeho stávající styl jednotný, i přesto že to není zrovna váš oblíbený.

  </section>

  <section id="line-width">

    <title>Šířka řádku</title>

    
Snažte se délku řádků v kódu udržet v rozmezí 80 až 120 znaků. Takové množství textu se vleze na většinu monitorů při použití slušné velikosti písma. Delší řádky může být obtížné číst a znamenají, že byste se měli zamyslet nad restrukturalizací svého kódu. Pokud mát příliš mnoho úrovní odsazení, rovněž to znamená, že byste měli svůj kód opravit.

  </section>

  <section id="indentation">

    <title>Odsazení</title>

    
Obecně je v kódu GNOME dávána přednost dvěma stylům odsazení.

    <list type="ordered">

      <item>

	
Styl linuxového jádra. K odsazení se používají tabulátory o šířce 8 znaků a složené závorky se umisťují neodsazené (tento styl bývá označován zkratkou K&R podle autorů Kernighan a Ritchie kultovní knihy The C Programming Language):

for (i = 0; i < num_elements; i++) {

	foo[i] = foo[i] + 42;

	if (foo[i] < 35) {

		printf ("Foo!");

		foo[i]--;

	} else {

		printf ("Bar!");

		foo[i]++;

	}

}

      </item>

      <item>

	
Styl GNU. Každá nová úroveň je odsazena 2 mezerami, složené závorky jsou samostatně na novém řádku a rovněž jsou odsazené.

for (i = 0; i < num_elements; i++)

  {

    foo[i] = foo[i] + 42;

    if (foo[i] < 35)

      {

        printf ("Foo!");

        foo[i]--;

      }

    else

      {

        printf ("Bar!");

        foo[i]++;

      }

  }

      </item>

    </list>

    
Oba styly mají své pro a proti. Nejdůležitější věcí ale je, aby okolní kód byl jednotný. Například knihovna GTK+, což je vývojářská sada pro widgety GNOME, je napsaná ve stylu GNU. Nautilus, což je správce souborů v GNOME, je napsán ve stylu linuxového jádra. Čitelné a jednotné jsou oba styly, ať použijete kterýkoliv z nich.

    
Když musíte studovat kus cizího kódu, který nemá vámi oblíbený styl odsazování, nebo na něm dokonce pracovat, dělá se vám z toho zle. Měli byste ale překonat své touhy všchno odsazení předělat nebo použít ve své záplatě jiný styl odsazování. Pamatujte na první pravidlo: dodržujte jednotnost a respektujte zvyky daného kódu, a vaše záplata bude mít daleko větší šanci na přijetí, aniž byste museli vést dohady o tom, který styl odsazování je lepší.

  </section>

  <section id="tab-characters">

    <title>Znaky tabulátor</title>

    
Nikdy neměňte šířku tabulátoru ve svém editoru. Ponechte ji na 8 mezerách. Pokud byste ji změnili, budete mít kód, který jste nepsali vy, věčně rozházený.

    
Místo toho si nastavte šířku odsazení odpovídající kódu, který upravujete. Když píšete v jiném stylu než linuxového jádra, můžete chtít říci svému editoru, aby automaticky převáděl všechny tabulátory na 8 mezer, takže nevzniknou žádné nejednoznačnosti týkající se množství mezer.

  </section>

  <section id="braces">

    <title>Závorky</title>

    
Složené závorky by se neměly používat pro blok s jediným příkazem:

/* dobře */

if (condition)

	single_statement ();

else

	another_single_statement (arg1);

	
Z tohoto pravidla existují čtyři výjimky:

	<list type="ordered">

          <item>

            
Ve stylu GNU, když má jedna část výrazu if-else závorky, měly by je mít obě, aby měly i stejné odsazení:

/* platný styl GNU */

if (condition)

  {

    foo ();

    bar ();

  }

else

  {

    baz ();

  }

/* špatně */

if (condition)

  {

    foo ();

    bar ();

  }

else

  baz ();

          </item>

	  <item>

	    
Samostatný výraz roztažený přes více řádků, např. funkce s hodně argumenty, a následovaný else nebo else if:

/* platný styl linuxového jádra */

if (condition) {

	a_single_statement_with_many_arguments (some_lengthy_argument,

						another_lengthy_argument,

						and_another_one,

						plus_one);

} else

	another_single_statement (arg1, arg2);

/* platný styl GNU */

if (condition)

  {

    a_single_statement_with_many_arguments (some_lengthy_argument,

                                            another_lengthy_argument,

                                            and_another_one,

                                            plus_one);

  }

else

  {

    another_single_statement (arg1, arg2);

  }

          </item>

          <item>

            
Když je podmínka rozdělená na více řádků:

/* platný styl linuxového jádra */

if (condition1 ||

    (condition2 && condition3) ||

    condition4 ||

    (condition5 && (condition6 || condition7))) {

	a_single_statement ();

}

/* platný styl GNU */

if (condition1 ||

    (condition2 && condition3) ||

    condition4 ||

    (condition5 && (condition6 || condition7)))

  {

    a_single_statement ();

  }

            
Uvědomte si ale, že takovéto dlouhé podmínky jsou náročné na porozumění. Proto je dobrým zvykem nastavit jednotlivé části podmínky do pravdivostních proměnných s popisnými názvy. Jinou možností je přesunout dlouhou podmínku do funkce.

          </item>

          <item>

            
Vnořené if v případě, že má být blok umístěn v nadřazeném if:

/* platný styl linuxového jádra */

if (condition) {

	if (another_condition)

		single_statement ();

	else

		another_single_statement ();

}

/* platný styl GNU */

if (condition)

  {

    if (another_condition)

      single_statement ();

    else

      another_single_statement ();

  }

/* špatně */

if (condition)

	if (another_condition)

		single_statement ();

	else if (yet_another_condition)

		another_single_statement ();

          </item>

        </list>

        
Obecně by nový blok měl být umístěn v nové úrovni odsazení, nějak takto:

int retval = 0;

statement_1 ();

statement_2 ();

{

	int var1 = 42;

	gboolean res = FALSE;

	res = statement_3 (var1);

	retval = res ? -1 : 1;

}

        
I když mají být složené závorky pro definici funkce na novém řádku, neměly by být odsazené:

/* platný styl linuxového jádra*/

static void

my_function (int argument)

{

	do_my_things ();

}

/* platný styl GNU */

static void

my_function (int argument)

{

  do_my_things ();

}

/* špatně */

static void

my_function (int argument) {

	do_my_things ();

}

/* špatně */

static void

my_function (int argument)

  {

    do_my_things ();

  }

  </section>

  <section id="conditions">

    <title>Podmínky</title>

    
U pravdivostních hodnot neprovádějte kontrolu na rovnost. Když ponecháte výchozí porovnání, bude výsledný kód čitelnější jakoby přirozená angličtina. Dalším logickým důvodem je, že skutečná hodnota „pravda“ nemusí nutně být totéž, co použití makra TRUE. Například:

/* špatně */

if (found == TRUE)

	do_foo ();

/* špatně */

if (found == FALSE)

	do_bar ();

/* dobře */

if (found)

	do_foo ();

/* dobře */

if (!found)

	do_bar ();

    
Jazyk C používá hodnotu 0 k mnoha účelům. Jako číselnou hodnotu, zakončení řetězce, prázdný ukazatel a pravdivostní hodnotu FALSE. Aby byl kód lépe čitelný, měli byste jej psát tak, aby byl konkrétní význam 0 zdůrazněn. Proto je při porovnávání dobré vědět, o jaký typ proměnné se jedná. U pravdivostních proměnných je výchozí porovnání v pořádku, protože se jedná o logický výraz. U ostatních typů samotných o logický výraz nejde, takže výslovné porovnání je lepší:

/* dobře */

if (some_pointer == NULL)

	do_blah ();

/* dobře */

if (number == 0)

	do_foo ();

/* dobře */

if (str != NULL && *str != '\0')

	do_bar ();

/* špatně */

if (!some_pointer)

	do_blah ();

/* špatně */

if (!number)

	do_foo ();

/* špatně */

if (str && *str)

	do_bar ();

  </section>

  <section id="functions">

    <title>Funkce</title>

    
Funkce by měly být deklarovány s návratovou hodnotou umístěnou na zvláštní řádek před názvem funkce:

void

my_function (void)

{

  …

}

    
Seznam argumentů musí být rozdělen na jednotlivé řádky pro každý z argumentů a názvy argumentů jsou správně zarovnané, přičemž se berou do úvahy ukazatele:

void

my_function (some_type_t      type,

             another_type_t  *a_pointer,

             double_ptr_t   **double_pointer,

             final_type_t     another_type)

{

  …

}

    
Pokud používáte Emacs, můžete vyžít M-x align k automatickému zarovnání tohoto typu. Stačí vložit okolo prototypu funkce bod a značku a vyvolat tento příkaz.

    
Zarovnání se dodržuje i při vyvolání funkce, která neporušuje omezení délky řádku:

align_function_arguments (first_argument,

                          second_argument,

                          third_argument);

  </section>

  <section id="whitespace">

    <title>Bílé znaky</title>

    
Vždy dejte mezeru před otevírací závorku, ale nikdy ne za ni:

/* dobře */

if (condition)

	do_my_things ();

/* dobře */

switch (condition) {

}

/* špatně */

if(condition)

	do_my_things();

/* špatně */

if ( condition )

	do_my_things ( );

    
Při deklaraci struktury oddělte její logické části pomocí prázdného řádku:

struct _GtkWrapBoxPrivate

{

	GtkOrientation        orientation;

	GtkWrapAllocationMode mode;

	GtkWrapBoxSpreading   horizontal_spreading;

	GtkWrapBoxSpreading   vertical_spreading;

	guint16               vertical_spacing;

	guint16               horizontal_spacing;

	guint16               minimum_line_children;

	guint16               natural_line_children;

	GList                *children;

};

    
Neodstraňujte bílé znaky a zalomení jen proto, že by se něco vlezlo na jeden řádek:

/* špatně */

if (condition) foo (); else bar ();

    
Odstraňte bílé znaky na koncích řádků, hlavně u samostatných záplat nebo zařazení. Nikdy nepoužívejte prázdné řádky na začátku nebo na konci souboru.

    
Zde je drobná funkce pro Emacs, kterou můžete použít k vyčištění bílých znaků na koncích řádků:

(defun clean-line-ends ()

  (interactive)

  (if (not buffer-read-only)

      (save-excursion

	(goto-char (point-min))

	(let ((count 0))

	  (while (re-search-forward "[ 	]+$" nil t)

	    (setq count (+ count 1))

	    (replace-match "" t t))

	  (message "Cleaned %d lines" count)))))

  </section>

  <section id="switch">

    <title>Výraz switch</title>

    
Příkaz switch by měl otevírat blok na nové úrovni odsazení a každý case by měl začínat na stejné úrovni, jako složené závorky, s příslušným blokem na nové úrovni odsazení:

/* platný styl linuxového jádra */

switch (condition) {

case FOO:

	do_foo ();

	break;

case BAR:

	do_bar ();

	break;

}

/* platný styl GNU */

switch (condition)

  {

  case FOO:

    do_foo ();

    break;

  case BAR:

    do_bar ();

    break;

  }

/* špatně */

switch (condition) {

  case FOO: do_foo (); break;

  case BAR: do_bar (); break;

}

/* špatně */

switch (condition)

  {

  case FOO: do_foo ();

    break;

  case BAR: do_bar ();

    break;

  }

/* špatně */

switch (condition)

  {

    case FOO:

    do_foo ();

    break;

    case BAR:

    do_bar ();

    break;

  }

    
Preferované, ale ne povinné, je oddělení různých případů prázdným řádkem:

switch (condition) {

case FOO:

	do_foo ();

	break;

case BAR:

	do_bar ();

	break;

default:

	do_default ();

}

    
Výraz break pro případ default není povinný.

    
Pokud přepínáte podle výčtového typu, musí být výraz case uveden pro všechny hodnoty daného výčtu. Hodnoty, které není potřeba obsloužit, uveďte dohromady s případem default:

switch (enumerated_condition) {

case HANDLED_1:

	do_foo ();

	break;

case HANDLED_2:

	do_bar ();

	break;

case IGNORED_1:

case IGNORED_2:

default:

	do_default ();

}

    
Pokud není potřeba obsloužit většinu z hodnot výčtu, měli byste pouvažovat spíš o výrazu if namísto switch.

    
Když blok case potřebuje deklarovat nové proměnné, použije se stejné pravidlo jako pro vnitřní blok (viz výše). Příkaz break by měl být umístěn mimo vnitřní blok:

/* platný styl GNU */

switch (condition)

  {

  case FOO:

    {

      int foo;

      foo = do_foo ();

    }

    break;

  …

  }

  </section>

  <section id="header-files">

    <title>Hlavičkové soubory</title>

    
Jediné hlavní pravidlo pro hlavičkové soubory je, že definici funkcí by měly být svisle zarovnané do tří sloupců:

return_type          function_name           (type   argument,

                                              type   argument,

                                              type   argument);

    
Maximální šířka jednotlivých sloupců je určena nejdelším prvkem ve sloupci:

void         gtk_type_set_property (GtkType      *type,

                                    const gchar  *value,

                                    GError      **error);

const gchar *gtk_type_get_property (GtkType      *type);

    
Sloupce je možné zarovnávat také na nejbližší tabulátor:

void          gtk_type_set_prop           (GtkType *type,

                                           gfloat   value);

gfloat        gtk_type_get_prop           (GtkType *type);

gint          gtk_type_update_foobar      (GtkType *type);

    
Jak již bylo uvedeno dříve, můžete v editoru Emacs použít M-x align, aby se to provedlo automaticky.

    
Když vytváříte veřejnou knihovnu, zkuste exportovat jediný veřejný hlavičkový soubor, ve kterém budou pomocí include vložené všechny menší hlavičkové soubory. Je to proto, aby veřejné hlavičky nikdy nebyly vložené přímo. Místo toho se v aplikacích použije jediná direktiva include. Například GTK+ ve svých hlavičkových souborech, který by neměl být aplikací vloženy přímo, používá následující:

#if !defined (__GTK_H_INSIDE__) && !defined (GTK_COMPILATION)

#error "Only <gtk/gtk.h> can be included directly."

#endif

    
U knihoven by všechny hlavičkové soubory měly mít ochranu proti vícenásobnému vložení (pro interní použití) a pro integraci s C++. Ta poskytuje magické extern "C", které vyžaduje C++ při vložení hlavičkového souboru prostého C:

#ifndef MYLIB_FOO_H_

#define MYLIB_FOO_H_

#include <gtk/gtk.h>

G_BEGIN_DECLS

…

G_END_DECLS

#endif /* MYLIB_FOO_H_ */

  </section>

  <section id="gobject">

    <title>Třídy GObject</title>

    
Definice a implementace třídy GObject vyžadují pár doplňujících poznámek ke stylu kódování a vždy by měly mít uveden <link xref="namespacing#gobject">správný jmenný prostor</link>.

    
Deklarace typedef by měly být umístěny na začátku souboru:

typedef struct _GtkBoxedStruct       GtkBoxedStruct;

typedef struct _GtkMoreBoxedStruct   GtkMoreBoxedStruct;

    
Včetně výčtových typů:

typedef enum

{

  GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT,

  GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH

} GtkSizeRequestMode;

    
A typů zpětných volání:

typedef void (* GtkCallback) (GtkWidget *widget,

                              gpointer   user_data);

    
Struktury instance by měly být deklarovány pomocí G_DECLARE_FINAL_TYPE nebo G_DECLARE_DERIVABLE_TYPE:

#define GTK_TYPE_FOO (gtk_foo_get_type ())

G_DECLARE_FINAL_TYPE (GtkFoo, gtk_foo, GTK, FOO, GtkWidget)

    
Pro konečné typy mohou být privátní data uchována ve struktuře, která by měla být definována v souboru C:

struct _GtkFoo

{

  GObject   parent_instance;

  guint     private_data;

  gpointer  more_private_data;

};

    
Pro typy, z který lze odvozovat další typy, musí být privátní data uchována v privátní struktuře v souboru C, která je nastavena pomocí G_DEFINE_TYPE_WITH_PRIVATE() a dostanete se k ní pomocí funkce _get_instance_private():

#define GTK_TYPE_FOO gtk_foo_get_type ()

G_DECLARE_DERIVABLE_TYPE (GtkFoo, gtk_foo, GTK, FOO, GtkWidget)

struct _GtkFooClass

{

  GtkWidgetClass parent_class;

  void (* handle_frob)  (GtkFrobber *frobber,

                         guint       n_frobs);

  gpointer padding[12];

};

    
Vždy používejte makra G_DEFINE_TYPE(), G_DEFINE_TYPE_WITH_PRIVATE() a G_DEFINE_TYPE_WITH_CODE() nebo jejich abstraktní varianty G_DEFINE_ABSTRACT_TYPE(), G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE() a G_DEFINE_ABSTRACT_TYPE_WITH_CODE(). Podobná makra používejte také pro definování rozhraní a boxované typy.

    
Mezi typy rozhraní by vždy měla být i vzorová definice typu pro účely přetypování:

typedef struct _GtkFooable          GtkFooable;

    
Struktura rozhraní by měla mít v definici typu k názvu přidáno „Interface“:

typedef struct _GtkFooableInterface     GtkFooableInterface;

    
Rozhraní musí mít následující makra:

	  
Makro

	  
Rozbalí se na

	  
GTK_TYPE_iface_name

	  
iface_name_get_type

	  
GTK_iface_name

	  
G_TYPE_CHECK_INSTANCE_CAST

	  
GTK_IS_iface_name

          
G_TYPE_CHECK_INSTANCE_TYPE

	  
GTK_iface_name_GET_IFACE

          
G_TYPE_INSTANCE_GET_INTERFACE

  </section>

  <section id="memory-allocation">

    <title>Přidělování paměti</title>

    
Když dynamicky alokujete data na haldě, použijte g_new().

    
Veřejné typy struktur by měly být vraceny vždy vynulované, buď výslovně pro jednotlivé členy struktury nebo pomocí g_new0().

    
Další podrobnosti viz <link xref="memory-management"/>.

  </section>

  <section id="macros">

    <title>Makra</title>

    
Snažte se vyhnout privátním makrům, pokud nejsou vysloveně nutná. Pamatujte na jejich zrušení pomocí #undef na konci bloku nebo funkce nebo série funkcí, které je potřebovali.

    
Před makry je obvykle dávána přednost vloženým funkcím.

    
Veřejná makra by se neměla používat, pokud nejsou vyhodnocována do konstanty.

  </section>

  <section id="public-api">

    <title>Veřejné API</title>

    
Vyhněte se exportování proměnných jako veřejné API, protože na některých platformách to může být nevhodné. Vždy místo toho dejte přednost funkcím pro získání a nastavení hodnoty. Zkuste se také vyhnout globálním proměnným.

  </section>

  <section id="private-api">

    <title>Privátní API</title>

    
Neexportované funkce, které jsou zapotřebí ve více než jednom zdrojovém souboru by měly mít prefix v podobě podtržítka („_“) a měly by být deklarovány v privátním hlavičkovém souboru. Například _mylib_internal_foo().

    
Funkce začínající podtržítkem nejsou nikdy exportovány.

    
Neexportované funkce, které jsou zapotřebí jen v jednom zdrojovém souboru by měly být deklarované jako statické.

  </section>

</page>