<?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="sv">

  <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+-gruppen</name>
    </credit>

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

    <desc>Våra riktlinjer för C-kod i GNOME</desc>
  
    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">
      <mal:name>Anders Jonsson</mal:name>
      <mal:email>anders.jonsson@norsjovallen.se</mal:email>
      <mal:years>2018</mal:years>
    </mal:credit>
  </info>

  <title>C-kodstil</title>

  <p>Detta dokument presenterar den föredragna kodstilen för C-program i GNOME. Medan kodstil väldigt mycket är en fråga om smak så föredrar vi i GNOME en kodstil som främjar konsekvens, läsbarhet och lätthet att underhålla.</p>

  <p>Vi presenterar exempel på bra kodstil så väl som exempel på dålig stil som inte är acceptabel i GNOME. Försök att skicka in patchar som följer GNOME:s kodstil, detta antyder att du gjort din läxa att respektera projektets mål av underhållbarhet i det långa loppet. Patchar med GNOME:s kodstil kommer också vara lättare att granska!</p>

  <note>
    <p>Detta dokument är för C-kod. För andra språk, se <link xref="index">huvudsidan</link> för programmeringsriktlinjerna för GNOME.</p>
  </note>

  <p>Dessa riktlinjer är kraftigt inspirerade av GTK:s dokument CODING-STYLE, Linuxkärnans CodingStyle samt GNU Coding Standards. Dessa är små variationer av varandra, med vissa modifieringar för varje projekts specifika behov och kultur, och GNOME:s version skiljer sig ej från detta.</p>

  <section id="most-important-rule">
    <title>Den absolut viktigaste regeln</title>

    <p>Den absolut viktigaste regeln vid skrivning av kod är detta: <em>titta på omgivande kod och försök imitera den</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>Så, vad än detta dokument rekommenderar, om det redan finns skriven kod som du patchar, behåll dess aktuella stil konsekvent även om det inte är din favoritstil.</p>
  </section>

  <section id="line-width">
    <title>Radbredd</title>

    <p>Försök att använda kodrader från 80 till 120 tecken långa. Denna textmängd passar lätt på de flesta skärmar med en rimlig typsnittsstorlek. Längre rader än så blir svåra att läsa, och betyder att du troligen bör strukturera om din kod. Om du har för många indenteringsnivåer betyder det i vilket fall att du borde fixa till din kod.</p>
  </section>

  <section id="indentation">
    <title>Indentering</title>

    <p>Allmänt finns det två föredragna indenteringsstilar för kod i GNOME.</p>

    <list type="ordered">
      <item>
	<p>
	  Linux Kernel style.  Tabs with a length of 8 characters are
	  used for the indentation, with K&amp;R brace placement:
	</p>

	<code style="valid">
for (i = 0; i &lt; num_elements; i++) {
	foo[i] = foo[i] + 42;

	if (foo[i] &lt; 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 &lt; num_elements; i++)
  {
    foo[i] = foo[i] + 42;

    if (foo[i] &lt; 35)
      {
        printf ("Foo!");
        foo[i]--;
      }
    else
      {
        printf ("Bar!");
        foo[i]++;
      }
  }</code>
      </item>
    </list>


    <p>Båda stilarna har sina för- och nackdelar. Det viktigaste är att <em>vara konsekvent</em> med omgivande kod. Exempelvis så är GTK+-biblioteket, GNOME:s komponentverktygslåda, skriven med GNU-stilen. Nautilus, GNOME:s filhanterare, är skriven i Linux-kärnans stil. Båda stilarna är fullständigt läsbara och konsekventa då du vant dig med dem.</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>Tabbtecken</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">
/* giltig */
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">
/* giltig GNU-stil */
if (condition)
  {
    foo ();
    bar ();
  }
else
  {
    baz ();
  }</code>

<code style="invalid">
/* ogiltig */
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">
/* giltig stil för Linux-kärnan */
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);

/* giltig GNU-stil */
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">
/* giltig stil för Linux-kärnan */
if (condition1 ||
    (condition2 &amp;&amp; condition3) ||
    condition4 ||
    (condition5 &amp;&amp; (condition6 || condition7))) {
	a_single_statement ();
}

/* giltig GNU-stil */
if (condition1 ||
    (condition2 &amp;&amp; condition3) ||
    condition4 ||
    (condition5 &amp;&amp; (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">
/* giltig stil för Linux-kärnan */
if (condition) {
	if (another_condition)
		single_statement ();
	else
		another_single_statement ();
}

/* giltig GNU-stil */
if (condition)
  {
    if (another_condition)
      single_statement ();
    else
      another_single_statement ();
  }</code>

<code style="invalid">
/* ogiltig */
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">
/* giltig stil för Linux-kärnan*/
static void
my_function (int argument)
{
	do_my_things ();
}

/* giltig GNU-stil*/
static void
my_function (int argument)
{
  do_my_things ();
}</code>

<code style="invalid">
/* ogiltig */
static void
my_function (int argument) {
	do_my_things ();
}

/* ogiltig */
static void
my_function (int argument)
  {
    do_my_things ();
  }</code>
  </section>

  <section id="conditions">
    <title>Villkor</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">
/* ogiltig */
if (found == TRUE)
	do_foo ();

/* ogiltig */
if (found == FALSE)
	do_bar ();</code>

    <code style="valid">
/* giltig */
if (found)
	do_foo ();

/* giltig */
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">
/* giltig */
if (some_pointer == NULL)
	do_blah ();

/* giltig */
if (number == 0)
	do_foo ();

/* giltig */
if (str != NULL &amp;&amp; *str != '\0')
	do_bar ();</code>

    <code style="invalid">
/* ogiltig */
if (!some_pointer)
	do_blah ();

/* ogiltig */
if (!number)
	do_foo ();

/* ogiltig */
if (str &amp;&amp; *str)
	do_bar ();</code>
  </section>

  <section id="functions">
    <title>Funktioner</title>

    <p>Funktioner bör deklareras genom att placera det returnerade värdet på en separat rad från funktionsnamnet:</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>Whitespace</title>

    <p>Placera alltid ett blanksteg före en inledande parentes men aldrig efter:</p>

    <code style="valid">
/* giltig */
if (condition)
	do_my_things ();

/* giltig */
switch (condition) {
}</code>

<code style="invalid">
/* ogiltig */
if(condition)
	do_my_things();

/* ogiltig */
if ( condition )
	do_my_things ( );</code>

    <p>Vid deklaration av en strukturtyp, använd nya rader för att separera logiska avsnitt av strukturen:</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>Ta inte bort blanksteg och nyrader bara för att något skulle rymmas på en enda rad:</p>

    <code style="invalid">
/* ogiltig */
if (condition) foo (); else bar ();</code>

    <p>Eliminera efterföljande blanksteg på alla rader, förslagsvis som en separat patch eller incheckning. Använd aldrig tomma rader i början eller i slutet på en fil.</p>

    <p>Det här är en liten Emacs-funktion som du kan använda för att rensa rader med efterföljande blanksteg:</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 "Rensade %d rader" count)))))</code>
  </section>

  <section id="switch">
    <title><code>switch</code>-satsen</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">
/* giltig stil för Linux-kärnan */
switch (condition) {
case FOO:
	do_foo ();
	break;

case BAR:
	do_bar ();
	break;
}

/* giltig GNU-stil */
switch (condition)
  {
  case FOO:
    do_foo ();
    break;

  case BAR:
    do_bar ();
    break;
  }</code>

<code style="invalid">
/* ogiltig */
switch (condition) {
  case FOO: do_foo (); break;
  case BAR: do_bar (); break;
}

/* ogiltig */
switch (condition)
  {
  case FOO: do_foo ();
    break;
  case BAR: do_bar ();
    break;
  }

/* ogiltig */
switch (condition)
  {
    case FOO:
    do_foo ();
    break;
    case BAR:
    do_bar ();
    break;
  }</code>

    <p>Det är önskvärt, men inte obligatoriskt, att separera de olika case-alternativen med en nyrad:</p>

    <code style="valid">
switch (condition) {
case FOO:
	do_foo ();
	break;

case BAR:
	do_bar ();
	break;

default:
	do_default ();
}</code>

    <p><code>break</code>-satsen för <code>default</code>-fallet är inte obligatorisk.</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">
/* giltig GNU-stil */
switch (condition)
  {
  case FOO:
    {
      int foo;

      foo = do_foo ();
    }
    break;

  …
  }</code>
  </section>

  <section id="header-files">
    <title>Headerfiler</title>

    <p>Den enda stora regeln för headerfiler är att funktionsdefinitionerna bör vara vertikalt justerade i tre kolumner:</p>

    <code style="valid">
return_type          function_name           (type   argument,
                                              type   argument,
                                              type   argument);</code>

    <p>Den maximala bredden för varje kolumn ges av det längsta elementet i kolumnen:</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>Det är också möjligt att justera kolumnerna till nästa tabb:</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>Som tidigare kan du använda <code>M-x align</code> i Emacs för att göra detta automatiskt.</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__) &amp;&amp; !defined (GTK_COMPILATION)
#error "Only &lt;gtk/gtk.h&gt; 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 &lt;gtk/gtk.h&gt;

G_BEGIN_DECLS

…

G_END_DECLS

#endif /* MYLIB_FOO_H_ */</code>
  </section>

  <section id="gobject">
    <title>GObject-klasser</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>
      And callback types:
    </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>Gränssnitt måste ha följande makron:</p>

    <table>
      <thead>
	<tr>
	  <td><p>Makro</p></td>
	  <td><p>Expanderas till</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>Minnesallokering</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>Se <link xref="memory-management"/> för mer detaljer.</p>
  </section>

  <section id="macros">
    <title>Makron</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>Öppet 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>Privat 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>Funktioner som inleds med understreck exporteras aldrig.</p>

    <p>Ej exporterade funktioner som bara behövs i en källkodsfil bör deklareras static.</p>
  </section>
</page>