Coding style

Wiki page by khorben on 28/10/2010 03:10:42
--- /var/www/www.defora.org/wiki/Coding style	2010/10/28 01:02:45	1.3
+++ /var/www/www.defora.org/wiki/Coding style	2010/10/28 01:08:08	1.4
@@ -1 +1 @@
-<h2>General rules</h2><h3>Indenting and spaces</h3>Throughout all of the project, a tab spacing of 8 spaces has been used. This is the default on most platforms, and the only one tolerated for the project.<br><br>Likewise, a maximum width of 80 characters per line is enforced, for the following reasons:<br><ul><li>it is easier to read shorter lines,<br></li><li>more generally, to maintain readability on each and every text console,</li><li>to be also as readable as likely on even smaller screens (eg embedded devices)</li><li>to enforce source code to be written with a maximum of three sub-scopes per function.</li></ul>Generally speaking, the natural indenting algorithm of the vim text editor is considered the correct one.<br><br>Spurious spaces at the end of lines, or lines containing solely white-space characters are forbidden.<br><h2>Specific to the C programming language</h2>Any function and variable that is not meant to be exported (available to other objects) must be declared "static", and prefixed with an underscore ("_").<br><br>The code is written in an object-oriented manner wherever possible, considering objects as pointers to hidden structs (through typedef definitions). Header files should be organized as follows:<br><br><pre>/* $Id: Coding\040style,v 1.3 2010/10/28 01:02:45 khorben Exp $ */<br>/* Copyright (c) Year Full Name &lt;email@addre.ss&gt; */<br>/* This file is part of DeforaOS Category Package */<br>/* License terms */<br><br><br><br>#ifndef PACKAGE_FILENAME_H<br># define PACKAGE_FILENAME_H<br><br># include &lt;header.h&gt;<br># include "optional.h"<br><br><br>/* Class */<br>/* public */<br>/* types */<br>typedef struct _Class Class;<br><br><br>/* functions */<br>Class * class_new(void);<br>void class_delete(Class * class);<br><br>/* accessors */<br>void class_set(Class * class, ...);<br><br>/* useful */<br>void class_operation(Class * class, ...);<br><br>#endif /* !PACKAGE_FILENAME_H */<br></pre><p>Likewise, source code should be presented as follows:</p><pre>/* $Id: Coding\040style,v 1.3 2010/10/28 01:02:45 khorben Exp $ */<br>/* Copyright (c) Year Full Name &lt;email@addre.ss&gt; */<br>/* This file is part of DeforaOS Category Package */<br>/* License terms */<br><br><br><br>#include &lt;other.h&gt;<br>#include "class.h"<br><br><br>/* Class */<br>/* private */<br>/* types */<br>struct _Class<br>{<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; /* ... */<br>};<br><br><br>/* constants */<br><br><br>/* variables */<br><br><br>/* prototypes */<br>static void _class_helper(Class * class, ...);<br><br><br>/* public */<br>/* functions */<br>/* class_new */<br>Class * class_new(void)<br>{<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Class * class;<br><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; return calloc(1, sizeof(*class));<br>}<br><br><br>/* class_delete */<br>void class_delete(Class * class)<br>{<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; free(class);<br>}<br><br><br>/* accessors */<br>void class_set(Class * class, ...)<br>{<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; /* ... */<br>}<br><br>/* useful */<br>void class_operation(Class * class, ...)<br>{<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; /* ... */<br>}<br><br><br>/* private */<br>/* functions */<br>static void _class_helper(Class * class, ...)<br>{<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; /* ... */<br>}<br></pre><br><pre></pre><h2>Specific to the Gtk+ library</h2>Any function that is not available in Gtk+ 2.4 should not be relied upon; the program must compile and work normally without them. It is encouraged to use newer, better functions when available; they must however be accompanied by an alternative version of the code (which may have less features).<br><br>Dialog windows should use the GtkDialog class by default.<br>
\ No newline at end of file
+<h2>General rules</h2><h3>Indenting and spaces</h3>Throughout all of the project, a tab spacing of 8 spaces has been used. This is the default on most platforms, and the only one tolerated for the project.<br><br>Likewise, a maximum width of 80 characters per line is enforced, for the following reasons:<br><ul><li>it is easier to read shorter lines,<br></li><li>more generally, to maintain readability on each and every text console,</li><li>to be also as readable as likely on even smaller screens (eg embedded devices)</li><li>to enforce source code to be written with a maximum of three sub-scopes per function.</li></ul>Generally speaking, the natural indenting algorithm of the vim text editor is considered the correct one.<br><br>Spurious spaces at the end of lines, or lines containing solely white-space characters are forbidden.<br><h2>Specific to the C programming language</h2>Any function and variable that is not meant to be exported (available to other objects) must be declared "static", and prefixed with an underscore ("_").<br><br>The code is written in an object-oriented manner wherever possible, considering objects as pointers to hidden structs (through typedef definitions). Header files should be organized as follows:<br><br><pre>/* $Id: Coding\040style,v 1.4 2010/10/28 01:08:08 khorben Exp $ */<br>/* Copyright (c) Year Full Name &lt;email@addre.ss&gt; */<br>/* This file is part of DeforaOS Category Package */<br>/* License terms */<br><br><br><br>#ifndef PACKAGE_FILENAME_H<br># define PACKAGE_FILENAME_H<br><br># include &lt;header.h&gt;<br># include "optional.h"<br><br><br>/* Class */<br>/* public */<br>/* types */<br>typedef struct _Class Class;<br><br><br>/* functions */<br>Class * class_new(void);<br>void class_delete(Class * class);<br><br>/* accessors */<br>void class_set(Class * class, ...);<br><br>/* useful */<br>void class_operation(Class * class, ...);<br><br>#endif /* !PACKAGE_FILENAME_H */<br></pre><p>Likewise, source code should be presented as follows:</p><pre>/* $Id: Coding\040style,v 1.4 2010/10/28 01:08:08 khorben Exp $ */<br>/* Copyright (c) Year Full Name &lt;email@addre.ss&gt; */<br>/* This file is part of DeforaOS Category Package */<br>/* License terms */<br><br><br><br>#include &lt;other.h&gt;<br>#include "class.h"<br><br><br>/* Class */<br>/* private */<br>/* types */<br>struct _Class<br>{<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; /* ... */<br>};<br><br><br>/* constants */<br><br><br>/* variables */<br><br><br>/* prototypes */<br>static void _class_helper(Class * class, ...);<br><br><br>/* public */<br>/* functions */<br>/* class_new */<br>Class * class_new(void)<br>{<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Class * class;<br><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; return calloc(1, sizeof(*class));<br>}<br><br><br>/* class_delete */<br>void class_delete(Class * class)<br>{<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; free(class);<br>}<br><br><br>/* accessors */<br>void class_set(Class * class, ...)<br>{<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; /* ... */<br>}<br><br>/* useful */<br>void class_operation(Class * class, ...)<br>{<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; /* ... */<br>}<br><br><br>/* private */<br>/* functions */<br>static void _class_helper(Class * class, ...)<br>{<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; /* ... */<br>}<br></pre><br><pre></pre><h2>Specific to the Gtk+ library</h2>Any function that is not available in Gtk+ 2.4 should not be relied upon; the program must compile and work normally without them. It is encouraged to use newer, better functions when available; they must however be accompanied by an alternative version of the code (which may have less features).<br><br>Generally speaking, any widget or function obsoleted at any point should be avoided whenever possible.<br><br>Dialog windows should use the GtkDialog class by default.<br><br>Any spacing set manually between widgets should be set to 4 pixels. This is easily managed through GtkHbox and GtkVbox:<br><ul><li>use gtk_vbox_new(TRUE/FALSE, 4) or gtk_hbox_new(TRUE/FALSE, 4)</li><li>pack widgets with zero additional spacing, as in gtk_box_pack_start(GTK_BOX(vbox), FALSE, TRUE, 0)</li><li>spacing between the box and its container should be set with gtk_container_set_width()</li></ul>The policy for scrolled windows should be set to automatic by default.<br><br>Tree views should be displayed with the rules hint set only when it improves readability.<br>
\ No newline at end of file
Revisions
NameDateAuthorMessage
1.7 (diff)khorben
1.6 (diff)khorben
1.5 (diff)khorben
1.4 (diff)khorben
1.3 (diff)khorben
1.2 (diff)khorben
1.1khorben