<?xml version="1.0" encoding="utf-8"?>
<page xmlns="http://projectmallard.org/1.0/" xmlns:its="http://www.w3.org/2005/11/its" type="topic" id="c-coding-style" xml:lang="el">
<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>Η ομάδα GTK+</name>
</credit>
<include xmlns="http://www.w3.org/2001/XInclude" href="cc-by-sa-3-0.xml"/>
<desc>Οι οδηγίες μας για κώδικα C στο GNOME</desc>
<mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">
<mal:name>Ελληνική μεταφραστική ομάδα GNOME</mal:name>
<mal:email>team@gnome.gr</mal:email>
<mal:years>2016</mal:years>
</mal:credit>
<mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">
<mal:name>Θάνος Τρυφωνίδης</mal:name>
<mal:email>tomtryf@gnome.org</mal:email>
<mal:years>2016</mal:years>
</mal:credit>
</info>
<title>Στυλ κώδικα C</title>
<p>
This document presents the preferred coding style for C programs
in GNOME. While coding style is very much a matter of taste, in
GNOME we favor a coding style that promotes consistency,
readability, and maintainability.
</p>
<p>
We present examples of good coding style as well as examples of
bad style that is not acceptable in GNOME. Please try to submit
patches that conform to GNOME’s coding style; this indicates that
you have done your homework to respect the project’s goal of
long-term maintainability. Patches with GNOME’s coding style will
also be easier to review!
</p>
<note>
<p>
This document is for C code. For other languages, check the
<link xref="index">main page</link> of the GNOME Programming
Guidelines.
</p>
</note>
<p>
These guidelines are heavily inspired by GTK’s CODING-STYLE
document, the Linux Kernel’s CodingStyle, and the GNU Coding
Standards. These are slight variations of each other, with
particular modifications for each project’s particular needs and
culture, and GNOME’s version is no different.
</p>
<section id="most-important-rule">
<title>The Single Most Important Rule</title>
<p>
The single most important rule when writing code is this:
<em>check the surrounding code and try to imitate it</em>.
</p>
<p>
As a maintainer it is dismaying to receive a patch that is
obviously in a different coding style to the surrounding code.
This is disrespectful, like someone tromping into a spotlessly-clean
house with muddy shoes.
</p>
<p>
So, whatever this document recommends, if there is already
written code and you are patching it, keep its current style
consistent even if it is not your favorite style.
</p>
</section>
<section id="line-width">
<title>Πλάτος γραμμής</title>
<p>
Try to use lines of code between 80 and 120 characters long.
This amount of text is easy to fit in most monitors with a
decent font size. Lines longer than that become hard to read,
and they mean that you should probably restructure your code.
If you have too many levels of indentation, it means that you
should fix your code anyway.
</p>
</section>
<section id="indentation">
<title>Εσοχή</title>
<p>Γενικά υπάρχουν δύο προτεινόμενα στυλ εσοχής κώδικα για το GNOME.</p>
<list type="ordered">
<item>
<p>Το στυλ Linux Kernel. Στηλοθέτες με μήκος 8 χαρακτήρων για εσοχή, με τοποθέτηση αγκίστρων K&R:</p>
<code style="valid">
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]++;
}
}</code>
</item>
<item>
<p>
GNU style. Each new level is indented by 2 spaces,
braces go on a line by themselves, and they are indented as
well.
</p>
<code style="valid">
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]++;
}
}</code>
</item>
</list>
<p>
Both styles have their pros and cons. The most important things
is to <em>be consistent</em> with the surrounding code. For
example, the GTK+ library, which is GNOME’s widget toolkit, is
written with the GNU style. Nautilus, GNOME’s file manager, is
written in Linux kernel style. Both styles are perfectly
readable and consistent when you get used to them.
</p>
<p>
Your first feeling when having to study or work on a piece of
code that doesn’t have your preferred indentation style may be,
how shall we put it, gut-wrenching. You should resist your
inclination to reindent everything, or to use an inconsistent
style for your patch. Remember the first rule: <em>be
consistent</em> and respectful of that code’s customs, and your
patches will have a much higher chance of being accepted without
a lot of arguing about the right indentation style.
</p>
</section>
<section id="tab-characters">
<title>Χαρακτήρες στηλοθέτη</title>
<p>
<em>Do not ever change the size of tabs in your editor</em>;
leave them as 8 spaces. Changing the size of tabs means that
code that you didn’t write yourself will be perpetually misaligned.
</p>
<p>
Instead, set the <em>indentation size</em> as appropriate for
the code you are editing. When writing in something other than
Linux kernel style, you may even want to tell your editor to
automatically convert all tabs to 8 spaces, so that there is no
ambiguity about the intended amount of space.
</p>
</section>
<section id="braces">
<title>Braces</title>
<p>
Curly braces should not be used for single statement blocks:
</p>
<code style="valid">
/* valid */
if (condition)
single_statement ();
else
another_single_statement (arg1);</code>
<p>
The “no block for single statements” rule has only four
exceptions:
</p>
<list type="ordered">
<item>
<p>
In GNU style, if either side of an if-else statement has
braces, both sides should, to match up indentation:
</p>
<code style="valid">
/* valid GNU style */
if (condition)
{
foo ();
bar ();
}
else
{
baz ();
}</code>
<code style="invalid">
/* invalid */
if (condition)
{
foo ();
bar ();
}
else
baz ();</code>
</item>
<item>
<p>
If the single statement covers multiple lines, e.g. for functions with
many arguments, and it is followed by <code>else</code> or
<code>else if</code>:
</p>
<code style="valid">
/* valid Linux kernel style */
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);
/* valid GNU style */
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);
}</code>
</item>
<item>
<p>
If the condition is composed of many lines:
</p>
<code style="valid">
/* valid Linux kernel style */
if (condition1 ||
(condition2 && condition3) ||
condition4 ||
(condition5 && (condition6 || condition7))) {
a_single_statement ();
}
/* valid GNU style */
if (condition1 ||
(condition2 && condition3) ||
condition4 ||
(condition5 && (condition6 || condition7)))
{
a_single_statement ();
}</code>
<p>
Note that such long conditions are usually hard to understand. A
good practice is to set the condition to a boolean variable, with
a good name for that variable. Another way is to move the long
condition to a function.
</p>
</item>
<item>
<p>
Nested <code>if</code>s, in which case the block should be placed
on the outermost <code>if</code>:
</p>
<code style="valid">
/* valid Linux kernel style */
if (condition) {
if (another_condition)
single_statement ();
else
another_single_statement ();
}
/* valid GNU style */
if (condition)
{
if (another_condition)
single_statement ();
else
another_single_statement ();
}</code>
<code style="invalid">
/* invalid */
if (condition)
if (another_condition)
single_statement ();
else if (yet_another_condition)
another_single_statement ();</code>
</item>
</list>
<p>
In general, new blocks should be placed on a new indentation level,
like this:
</p>
<code style="valid">
int retval = 0;
statement_1 ();
statement_2 ();
{
int var1 = 42;
gboolean res = FALSE;
res = statement_3 (var1);
retval = res ? -1 : 1;
}</code>
<p>
While curly braces for function definitions should rest on a
new line they should not add an indentation level:
</p>
<code style="valid">
/* valid Linux kernel style*/
static void
my_function (int argument)
{
do_my_things ();
}
/* valid GNU style*/
static void
my_function (int argument)
{
do_my_things ();
}</code>
<code style="invalid">
/* invalid */
static void
my_function (int argument) {
do_my_things ();
}
/* invalid */
static void
my_function (int argument)
{
do_my_things ();
}</code>
</section>
<section id="conditions">
<title>Συνθήκες</title>
<p>
Do not check boolean values for equality. By using implicit
comparisons, the resulting code can be read more like conversational
English. Another rationale is that a ‘true’ value may not be necessarily
equal to whatever the <code>TRUE</code> macro uses. For example:
</p>
<code style="invalid">
/* invalid */
if (found == TRUE)
do_foo ();
/* invalid */
if (found == FALSE)
do_bar ();</code>
<code style="valid">
/* valid */
if (found)
do_foo ();
/* valid */
if (!found)
do_bar ();</code>
<p>
The C language uses the value 0 for many purposes. As a numeric value,
the end of a string, a null pointer and the <code>FALSE</code> boolean.
To make the code clearer, you should write code that highlights the
specific way 0 is used. So when reading a comparison, it is possible to
know the variable type. For boolean variables, an implicit comparison is
appropriate because it’s already a logical expression. Other variable
types are not logical expressions by themselves, so an explicit
comparison is better:
</p>
<code style="valid">
/* valid */
if (some_pointer == NULL)
do_blah ();
/* valid */
if (number == 0)
do_foo ();
/* valid */
if (str != NULL && *str != '\0')
do_bar ();</code>
<code style="invalid">
/* invalid */
if (!some_pointer)
do_blah ();
/* invalid */
if (!number)
do_foo ();
/* invalid */
if (str && *str)
do_bar ();</code>
</section>
<section id="functions">
<title>Συναρτήσεις</title>
<p>
Functions should be declared by placing the returned value on a
separate line from the function name:
</p>
<code style="valid">
void
my_function (void)
{
…
}</code>
<p>
The argument list must be broken into a new line for each
argument, with the argument names right aligned, taking into
account pointers:
</p>
<code style="valid">
void
my_function (some_type_t type,
another_type_t *a_pointer,
double_ptr_t **double_pointer,
final_type_t another_type)
{
…
}</code>
<p>
If you use Emacs, you can use <code>M-x align</code> to do this
kind of alignment automatically. Just put the point and mark
around the function’s prototype, and invoke that command.
</p>
<p>
The alignment also holds when invoking a function without breaking the
line length limit:
</p>
<code style="valid">
align_function_arguments (first_argument,
second_argument,
third_argument);</code>
</section>
<section id="whitespace">
<title>Κενά διαστήματα</title>
<p>Προσθέστε πάντα ένα διάστημα πριν το άνοιγμα μιας παρένθεσης αλλά ποτέ μετά:</p>
<code style="valid">
/* valid */
if (condition)
do_my_things ();
/* valid */
switch (condition) {
}</code>
<code style="invalid">
/* invalid */
if(condition)
do_my_things();
/* invalid */
if ( condition )
do_my_things ( );</code>
<p>Όταν ορίζετε μια δομή χρησιμοποιήστε νέες γραμμές για να διαχωρίσετε τα λογικά κομμάτια της δομής:</p>
<code style="valid">
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;
};</code>
<p>
Do not eliminate whitespace and newlines just because something would
fit on a single line:
</p>
<code style="invalid">
/* invalid */
if (condition) foo (); else bar ();</code>
<p>
Do eliminate trailing whitespace on any line, preferably as a separate
patch or commit. Never use empty lines at the beginning or at the end of
a file.
</p>
<p>Παρακάτω ακολουθεί μια συνάρτηση Emacs με την οποία μπορείτε να καθαρίσετε τις γραμμές με κενά διαστήματα στο τέλος αυτής.</p>
<code>
(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)))))</code>
</section>
<section id="switch">
<title>Η συνθήκη <code>switch</code></title>
<p>
A <code>switch</code> should open a block on a new
indentation level, and each <code>case</code> should start on
the same indentation level as the curly braces, with the case
block on a new indentation level:
</p>
<code style="valid">
/* valid Linux kernel style */
switch (condition) {
case FOO:
do_foo ();
break;
case BAR:
do_bar ();
break;
}
/* valid GNU style */
switch (condition)
{
case FOO:
do_foo ();
break;
case BAR:
do_bar ();
break;
}</code>
<code style="invalid">
/* invalid */
switch (condition) {
case FOO: do_foo (); break;
case BAR: do_bar (); break;
}
/* invalid */
switch (condition)
{
case FOO: do_foo ();
break;
case BAR: do_bar ();
break;
}
/* invalid */
switch (condition)
{
case FOO:
do_foo ();
break;
case BAR:
do_bar ();
break;
}</code>
<p>
It is preferable, though not mandatory, to separate the various
cases with a newline:
</p>
<code style="valid">
switch (condition) {
case FOO:
do_foo ();
break;
case BAR:
do_bar ();
break;
default:
do_default ();
}</code>
<p>
The <code>break</code> statement for the <code>default</code> case is not
mandatory.
</p>
<p>
If switching over an enumerated type, a <code>case</code> statement must
exist for every member of the enumerated type. For members you do not
want to handle, alias their <code>case</code> statements to
<code>default</code>:
</p>
<code style="valid">
switch (enumerated_condition) {
case HANDLED_1:
do_foo ();
break;
case HANDLED_2:
do_bar ();
break;
case IGNORED_1:
case IGNORED_2:
default:
do_default ();
}</code>
<p>
If most members of the enumerated type should not be handled, consider
using an <code>if</code> statement instead of a <code>switch</code>.
</p>
<p>
If a <code>case</code> block needs to declare new variables, the same rules as the
inner blocks apply (see above); the <code>break</code> statement should be placed
outside of the inner block:
</p>
<code style="valid">
/* valid GNU style */
switch (condition)
{
case FOO:
{
int foo;
foo = do_foo ();
}
break;
…
}</code>
</section>
<section id="header-files">
<title>Κεφαλίδες</title>
<p>
The only major rule for headers is that the function definitions
should be vertically aligned in three columns:
</p>
<code style="valid">
return_type function_name (type argument,
type argument,
type argument);</code>
<p>
The maximum width of each column is given by the longest element
in the column:
</p>
<code style="valid">
void gtk_type_set_property (GtkType *type,
const gchar *value,
GError **error);
const gchar *gtk_type_get_property (GtkType *type);</code>
<p>
It is also possible to align the columns to the next tab:
</p>
<code style="valid">
void gtk_type_set_prop (GtkType *type,
gfloat value);
gfloat gtk_type_get_prop (GtkType *type);
gint gtk_type_update_foobar (GtkType *type);</code>
<p>
As before, you can use <code>M-x align</code> in Emacs to do
this automatically.
</p>
<p>
If you are creating a public library, try to export a single
public header file that in turn includes all the smaller header
files into it. This is so that public headers are never
included directly; rather a single include is used in
applications. For example, GTK+ uses the following in its
header files that should not be included directly by
applications:
</p>
<code style="valid">
#if !defined (__GTK_H_INSIDE__) && !defined (GTK_COMPILATION)
#error "Only <gtk/gtk.h> can be included directly."
#endif</code>
<p>
For libraries, all headers should have inclusion guards (for
internal usage) and C++ guards. These provide the <code>extern
"C"</code> magic that C++ requires to include plain C headers:
</p>
<code style="valid">
#ifndef MYLIB_FOO_H_
#define MYLIB_FOO_H_
#include <gtk/gtk.h>
G_BEGIN_DECLS
…
G_END_DECLS
#endif /* MYLIB_FOO_H_ */</code>
</section>
<section id="gobject">
<title>Κλάσεις GObject</title>
<p>
GObject class definitions and implementations require some
additional coding style notices, and should always be
<link xref="namespacing#gobject">correctly namespaced</link>.
</p>
<p>
Typedef declarations should be placed at the beginning of the file:
</p>
<code style="valid">
typedef struct _GtkBoxedStruct GtkBoxedStruct;
typedef struct _GtkMoreBoxedStruct GtkMoreBoxedStruct;</code>
<p>
This includes enumeration types:
</p>
<code style="valid">
typedef enum
{
GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT,
GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH
} GtkSizeRequestMode;</code>
<p>Και τύπους επανάκλησης:</p>
<code style="valid">
typedef void (* GtkCallback) (GtkWidget *widget,
gpointer user_data);</code>
<p>
Instance structures should be declared using
<code>G_DECLARE_FINAL_TYPE</code> or
<code>G_DECLARE_DERIVABLE_TYPE</code>:
</p>
<code style="valid">
#define GTK_TYPE_FOO (gtk_foo_get_type ())
G_DECLARE_FINAL_TYPE (GtkFoo, gtk_foo, GTK, FOO, GtkWidget)</code>
<p>
For final types, private data can be stored in the object struct, which
should be defined in the C file:
</p>
<code style="valid">
struct _GtkFoo
{
GObject parent_instance;
guint private_data;
gpointer more_private_data;
};</code>
<p>
For derivable types, private data must be stored in a private struct in
the C file, configured using <code>G_DEFINE_TYPE_WITH_PRIVATE()</code>
and accessed using a <code>_get_instance_private()</code> function:
</p>
<code style="valid">
#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];
};</code>
<p>
Always use the <code>G_DEFINE_TYPE()</code>,
<code>G_DEFINE_TYPE_WITH_PRIVATE()</code>, and
<code>G_DEFINE_TYPE_WITH_CODE()</code> macros, or their abstract variants
<code>G_DEFINE_ABSTRACT_TYPE()</code>,
<code>G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE()</code>,
and <code>G_DEFINE_ABSTRACT_TYPE_WITH_CODE()</code>; also, use the similar
macros for defining interfaces and boxed types.
</p>
<p>
Interface types should always have the dummy typedef for cast
purposes:
</p>
<code style="valid">
typedef struct _GtkFooable GtkFooable;</code>
<p>
The interface structure should have ‘Interface’ postfixed to the
dummy typedef:
</p>
<code style="valid">
typedef struct _GtkFooableInterface GtkFooableInterface;</code>
<p>
Interfaces must have the following macros:
</p>
<table>
<thead>
<tr>
<td><p>Μακροεντολή</p></td>
<td><p>Expands to</p></td>
</tr>
</thead>
<tbody>
<tr>
<td><p><code>GTK_TYPE_<var>iface_name</var></code></p></td>
<td><p><code><var>iface_name</var>_get_type</code></p></td>
</tr>
<tr>
<td><p><code>GTK_<var>iface_name</var></code></p></td>
<td><p><code>G_TYPE_CHECK_INSTANCE_CAST</code></p></td>
</tr>
<tr>
<td><p><code>GTK_IS_<var>iface_name</var></code></p></td>
<td><p><code>G_TYPE_CHECK_INSTANCE_TYPE</code></p></td>
</tr>
<tr>
<td><p><code>GTK_<var>iface_name</var>_GET_IFACE</code></p></td>
<td><p><code>G_TYPE_INSTANCE_GET_INTERFACE</code></p></td>
</tr>
</tbody>
</table>
</section>
<section id="memory-allocation">
<title>Memory Allocation</title>
<p>
When dynamically allocating data on the heap use <code>g_new()</code>.
</p>
<p>
Public structure types should always be returned after being
zero-ed, either explicitly for each member, or by using
<code>g_new0()</code>.
</p>
<p>Για περισσότερες λεπτομέρειες δείτε <link xref="memory-management"/>.</p>
</section>
<section id="macros">
<title>Μακροεντολές</title>
<p>
Try to avoid private macros unless strictly necessary. Remember
to <code>#undef</code> them at the end of a block or a series of functions
needing them.
</p>
<p>
Inline functions are usually preferable to private macros.
</p>
<p>
Public macros should not be used unless they evaluate to a
constant.
</p>
</section>
<section id="public-api">
<title>Δημόσιο API</title>
<p>
Avoid exporting variables as public API, since this is
cumbersome on some platforms. It is always preferable to add
getters and setters instead. Also, beware global variables in
general.
</p>
</section>
<section id="private-api">
<title>Ιδιωτικό API</title>
<p>
Non-exported functions that are needed in more than one source file
should be prefixed with an underscore (‘_’), and declared in a
private header file. For example, <code>_mylib_internal_foo()</code>.
</p>
<p>
Underscore-prefixed functions are never exported.
</p>
<p>
Non-exported functions that are only needed in one source file
should be declared static.
</p>
</section>
</page>