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í.
Tento dokument se týká kódu v jazyce C. Na další jazyky se podívejte na hlavní stránku pokynů k programování v GNOME.
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.
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ý.
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.
Obecně je v kódu GNOME dávána přednost dvěma stylům odsazení.
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]++;
}
}
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]++;
}
}
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ší.
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.
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:
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 ();
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);
}
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.
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 ();
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 ();
}
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 ();
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);
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)))))
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;
…
}
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_ */
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 správný jmenný prostor.
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 |
|
|
|
|
|
|
|
|
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 .
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.
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.
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é.