HACKING

   1 Contributing to pacman
   2 ======================
   3
   4 In addition to this file, please read `submitting-patches` and
   5 `translation-help` in the same directory for additional info on contributing.
   6
   7 Coding style
   8 ------------
   9
  10 1.  All code should be indented with tabs. (Ignore the use of only spaces in
  11     this file) By default, source files contain the following VIM modeline:
  12 +
  13 [C]
  14 code~~~~~~~~~~
  15 /* vim: set ts=2 sw=2 noet: */
  16 code~~~~~~~~~~
  17
  18 2.  When opening new blocks such as 'while', 'if', or 'for', leave the opening
  19     brace on the same line as the beginning of the codeblock. The closing brace
  20     gets its own line (the only exception being 'else'). Do not use extra
  21     spaces around the parentheses of the block. ALWAYS use opening and closing
  22     braces, even if it's just a one-line block. This reduces future error when
  23     blocks are expanded beyond one line.
  24 +
  25 [C]
  26 code~~~~~~~~~~
  27 for(lp = list; lp; lp = lp->next) {
  28   newlist = _alpm_list_add(newlist, strdup(lp->data));
  29 }
  30
  31 while(it) {
  32   ptr = it->next;
  33   if(fn) {
  34     fn(it->data);
  35   } else {
  36     return(1);
  37   }
  38   free(it);
  39   it = ptr;
  40 }
  41 code~~~~~~~~~~
  42
  43 3.  When declaring a new function, put the opening and closing braces on their
  44     own line. Also, when declaring a pointer, do not put a space between the
  45     asterisk and the variable name.
  46 +
  47 [C]
  48 code~~~~~~~~~~
  49 alpm_list_t *alpm_list_add(alpm_list_t *list, void *data)
  50 {
  51   alpm_list_t *ptr, *lp;
  52
  53   ptr = list;
  54   if(ptr == NULL) {
  55   ...
  56   }
  57   ...
  58 }
  59 code~~~~~~~~~~
  60
  61 4.  Comments should be ANSI-C89 compliant. That means no `// Comment` style;
  62     use only `/* Comment */` style.
  63
  64     /* This is a comment */
  65        NOT
  66     // This is a comment
  67
  68 5.  Return statements should be written like a function call.
  69
  70     return(0);
  71        NOT
  72     return 0;
  73
  74 6.  The sizeof() operator should accept a type, not a value. (TODO: in certain
  75     cases, it may be better- should this be a set guideline? Read "The Practice
  76     of Programming")
  77
  78     sizeof(alpm_list_t);
  79        NOT
  80     sizeof(*mylist);
  81
  82 7.  When using strcmp() (or any function that returns 0 on success) in a
  83     conditional statement, use != 0 or == 0 and not the negation (!) operator.
  84     It reads much cleaner for humans (using a negative to check for success is
  85     confusing) and the compiler will treat it correctly anyway.
  86
  87     if(strcmp(a, b) == 0)
  88        NOT
  89     if(!strcmp(a, b))
  90
  91
  92 Other Concerns
  93 --------------
  94
  95 Header Includes
  96 ~~~~~~~~~~~~~~~
  97
  98 Currently our #include usage is in messy shape, but this is no reason to
  99 continue down this messy path. When adding an include to a file, follow this
 100 general pattern, including blank lines:
 101
 102 [C]
 103 code~~~~~~~~~~
 104 #include "config.h"
 105
 106 #include <standardheader.h>
 107 #include <another.h>
 108 #include <...>
 109 code~~~~~~~~~~
 110
 111 Follow this with some more headers, depending on whether the file is in libalpm
 112 or pacman proper. For libalpm:
 113
 114 [C]
 115 code~~~~~~~~~~
 116 /* libalpm */
 117 #include "yourfile.h"
 118 #include "alpm_list.h"
 119 #include "anythingelse.h"
 120 code~~~~~~~~~~
 121
 122 For pacman:
 123
 124 [C]
 125 code~~~~~~~~~~
 126 #include <alpm.h>
 127 #include <alpm_list.h>
 128
 129 /* pacman */
 130 #include "yourfile.h"
 131 #include "anythingelse.h"
 132 code~~~~~~~~~~
 133
 134 /////
 135 vim: set ts=2 sw=2 syntax=asciidoc et:
 136 /////