git.sesse.net Git - vlc/blob - doc/developer2/coding.xml

   1 <chapter><title>Coding rules</title>
   2
   3 <sect1><title>Naming conventions</title>
   4
   5 <sect2><title>Functions</title>
   6
   7       <para>
   8 All functions are named accordingly : module name (in lower case) + _ +
   9 function name (in mixed case, <emphasis> without underscores</emphasis>).
  10 For instance : <function>intf_FooFunction</function>. Static functions
  11 don't need usage of the module name.
  12       </para>
  13
  14 </sect2>
  15
  16 <sect2><title>Variables</title>
  17
  18       <para>
  19 Hungarian notations are used, that means we have the following prefixes :
  20       </para>
  21
  22       <itemizedlist>
  23         <listitem> <para> i_ for integers (sometimes l_ for long integers) ;
  24         </para> </listitem>
  25         <listitem> <para> b_ for booleans ; </para> </listitem>
  26         <listitem> <para> d_ for doubles (sometimes f_ for floats) ;
  27         </para> </listitem>
  28         <listitem> <para> pf_ for function pointers ; </para> </listitem>
  29         <listitem> <para> psz_ for a Pointer to a String terminated by a
  30         Zero (C-string) ;
  31         </para> </listitem>
  32         <listitem> <para> More generally, we add a p when the variable is
  33         a pointer to a type. </para> </listitem>
  34       </itemizedlist>
  35
  36       <para>
  37 If one variable has no basic type (for instance a complex structure), don't
  38 put any prefix (except p_* if it's a pointer). After one prefix, put
  39 an <emphasis> explicit </emphasis> variable name <emphasis> in lower
  40 case</emphasis>. If several words are required, join them with an
  41 underscore (no mixed case). Examples :
  42       </para>
  43
  44       <itemizedlist>
  45         <listitem> <para>
  46         <type> data_packet_t * </type> <varname> p_buffer; </varname>
  47         </para> </listitem> <listitem> <para>
  48         <type> char </type> <varname> psz_msg_date[42]; </varname>
  49         </para> </listitem> <listitem> <para>
  50         <type> int </type> <varname> pi_es_refcount[MAX_ES]; </varname>
  51         </para> </listitem> <listitem> <para>
  52         <type> void </type> <varname> (* pf_next_data_packet)( int * ); </varname>
  53         </para> </listitem>
  54       </itemizedlist>
  55
  56     </sect2>
  57
  58
  59
  60 </sect1>
  61
  62 <sect1><title>Code indentation</title>
  63
  64 <para>Code is indented with 4 spaces. Never use tabs in the source
  65 code. If you are using Vim as your editor, you can use <command>set
  66 expandtab</command>.</para>
  67
  68 <para>Please put spaces <emphasis> before and after </emphasis> operators, and
  69 inside brackets. For instance :
  70 <programlisting> for( i = 0; i &lt; 12; i++, j += 42 ); </programlisting>
  71       </para>
  72
  73       <para>
  74 Third, leave braces alone on their lines (GNU style). For instance :
  75         <programlisting>
  76 if( i_es == 42 )
  77 {
  78    p_buffer[0] = 0x12;
  79 }
  80         </programlisting>
  81       </para>
  82
  83       <para>
  84 We write C, so use C-style comments /* ... */.
  85       </para>
  86
  87 </sect1>
  88
  89 </chapter>