Documentation/CodingStyle.yo

   1 report(CodingStyle - standards while programming for GNU
   2 LilyPond)(Han-Wen Nienhuys and Jan Nieuwenhuizen)()()
   3
   4 nsect(DESCRIPTION)
   5
   6 We use these standards while doing programming for GNU LilyPond.  If
   7 you do some hacking, we appreciate it if you would follow this rules,
   8 but if you don't, we still like you.
   9
  10 Functions and methods do not return errorcodes.
  11
  12 quote(
  13
  14 A program should be light and agile, its subroutines
  15 connected like a string of pearls.  The spirit and intent of
  16 the program should be retained throughout.  There should be
  17 neither too little nor too much, neither needless loops nor
  18 useless variables, neither lack of structure nor overwhelming
  19 rigidity.
  20
  21 A program should follow the 'Law of Least
  22 Astonishment'.  What is this law?  It is simply that the
  23 program should always respond to the user in the way that
  24 astonishes him least.
  25
  26 A program, no matter how complex, should act as a
  27 single unit.  The program should be directed by the logic
  28 within rather than by outward appearances.
  29
  30 If the program fails in these requirements, it will be
  31 in a state of disorder and confusion.  The only way to correct
  32 this is to rewrite the program.
  33
  34 -- Geoffrey James, "The Tao of Programming"
  35 )
  36
  37
  38 nsubsect(LANGUAGES)
  39
  40 C++, /bin/sh and Python are preferred.  Perl is not.
  41 Python code should use an indent of 8, using TAB characters.
  42
  43 nsubsect(FILES)
  44
  45 Definitions of classes that are only accessed via pointers
  46 (*) or references (&) shall not be included as include files.
  47
  48 filenames
  49
  50 verb(
  51         ".hh"   Include files
  52         ".cc"   Implementation files
  53         ".icc"  Inline definition files
  54         ".tcc"  non inline Template defs
  55 )
  56
  57 in emacs:
  58
  59 verb(
  60         (setq auto-mode-alist
  61               (append '(("\\.make$" . makefile-mode)
  62                         ("\\.cc$" . c++-mode)
  63                         ("\\.icc$" . c++-mode)
  64                         ("\\.tcc$" . c++-mode)
  65                         ("\\.hh$" . c++-mode)
  66                         ("\\.pod$" . text-mode)
  67                         )
  68                       auto-mode-alist))
  69 )
  70
  71
  72 The class Class_name_abbreviation is coded in file(class-name-abbr.*)
  73
  74
  75 nsubsect(INDENTATION)
  76
  77 in emacs:
  78
  79 verb(
  80         (add-hook 'c++-mode-hook
  81                   '(lambda() (c-set-style "gnu")
  82                      )
  83                   )
  84 )
  85
  86 If you like using font-lock, you can also add this to your file(.emacs):
  87
  88 verb(
  89         (setq font-lock-maximum-decoration t)
  90         (setq c++-font-lock-keywords-3
  91               (append
  92                c++-font-lock-keywords-3
  93                '(("\\b\\([a-zA-Z_]+_\\)\\b" 1 font-lock-variable-name-face)
  94                ("\\b\\([A-Z]+[a-z_]+\\)\\b" 1 font-lock-type-face))
  95                ))
  96 )
  97
  98 nsubsect(CLASSES and TYPES:)
  99
 100 verb(
 101         This_is_a_class
 102 )
 103
 104 nsubsect(MEMBERS)
 105
 106 verb(
 107         Class::member ()
 108         Type Class::member_type_
 109         Type Class::member_type ()
 110 )
 111
 112 the code(type) is a Hungarian notation postfix for code(Type). See below
 113
 114 nsubsect(MACROS)
 115
 116 Macros should be written completely in uppercase
 117
 118 The code should not be compilable if proper macro declarations are not
 119 included.
 120
 121 Don't laugh. It took us a whole evening/night to figure out one of
 122 these bugs, because we had a macro that looked like
 123 code(DECLARE_VIRTUAL_FUNCTIONS ()).
 124
 125 nsubsect(BROKEN CODE)
 126
 127 Broken code (hardwired dependencies, hardwired constants, slow
 128 algorithms and obvious limitations) should be marked as such: either
 129 with a verbose TODO, or with a short "ugh" comment.
 130
 131 nsubsect(COMMENTS)
 132
 133 The source is commented in the DOC++ style.  Check out doc++ at
 134 lurl(http://www.zib.de/Visual/software/doc++/index.html)
 135
 136 verb(
 137         /*
 138                 C style comments for multiline comments.
 139                 They come before the thing to document.
 140                 [...]
 141         */
 142
 143
 144         /**
 145                 short description.
 146                 Long class documentation.
 147                 (Hungarian postfix)
 148
 149                 TODO Fix boring_member ()
 150         */
 151         class Class {
 152                 /**
 153                   short description.
 154                   long description
 155                 */
 156
 157                 Data data_member_;
 158
 159
 160                 /**
 161                         short memo. long doco of member ()
 162                         @param description of arguments
 163                         @return Rettype
 164                 */
 165                 Rettype member (Argtype);
 166
 167                 /// memo only
 168                 boring_member () {
 169                         data_member_ = 121; // ugh
 170                 }
 171         };
 172 )
 173
 174
 175 Unfortunately most of the code isn't really documented that good.
 176
 177
 178 nsubsect(MEMBERS (2))
 179
 180 Standard methods:
 181
 182 verb(
 183         ///check that *this satisfies its invariants, abort if not.
 184         void OK () const
 185
 186         /// print *this (and substructures) to debugging log
 187         void print () const
 188
 189         /**
 190         protected member. Usually invoked by non-virtual XXXX ()
 191         */
 192         virtual do_XXXX ()
 193
 194         /**add some data to *this.
 195         Presence of these methods usually imply that it is not feasible to this
 196         via  a constructor
 197         */
 198         add (..)
 199
 200         /// replace some data of *this
 201         set (..)
 202 )
 203
 204 nsubsect(Constructor)
 205
 206 Every class should have a default constructor.
 207
 208 Don't use non-default constructors if this can be avoided:
 209
 210 verb(
 211         Foo f(1)
 212 )
 213
 214 is less readable than
 215
 216 verb(
 217         Foo f;
 218         f.x = 1
 219 )
 220
 221 or
 222
 223 verb(
 224         Foo f(Foo_convert::int_to_foo (1))
 225 )
 226
 227 nsect(HUNGARIAN NOTATION NAMING CONVENTION)
 228
 229 Proposed is a naming convention derived from the so-called
 230 em(Hungarian Notation).  Macros, code(enum)s and code(const)s are all
 231 uppercase, with the parts of the names separated by underscores.
 232
 233 nsubsect(Types)
 234
 235 description(
 236 dit(code(byte))
 237     unsigned char. (The postfix _by is ambiguous)
 238 dit(code(b))
 239     bool
 240 dit(code(bi))
 241     bit
 242 dit(code(ch))
 243     char
 244 dit(code(f))
 245     float
 246 dit(code(i))
 247     signed integer
 248 dit(code(str))
 249     string class
 250 dit(code(sz))
 251     Zero terminated c string
 252 dit(code(u))
 253     unsigned integer
 254 )
 255
 256 nsubsect(User defined types)
 257
 258 verb(
 259         /** Slur blah. blah.
 260         (slur)
 261         */
 262         class Slur {};
 263         Slur* slur_p = new Slur;
 264 )
 265
 266 nsubsect(Modifiers)
 267
 268 The following types modify the meaning of the prefix.
 269 These are preceded by the prefixes:
 270
 271 description(
 272 dit(code(a))
 273     array
 274 dit(code(array))
 275     user built array.
 276 dit(code(c))
 277     const. Note that the proper order is code(Type const)
 278     i.s.o. code(const Type)
 279 dit(code(C))
 280     A const pointer. This would be equivalent to code(_c_l), but since any
 281     "const" pointer has to be a link (you can't delete a const pointer),
 282     it is superfluous.
 283 dit(code(l))
 284     temporary pointer to object (link)
 285 dit(code(p))
 286     pointer to newed object
 287 dit(code(r))
 288     reference
 289 )
 290
 291 nsubsect(Adjective)
 292
 293 Adjectives such as global and static should be spelled out in full.
 294 They come before the noun that they refer to, just as in normal english.
 295
 296 verb(
 297 foo_global_i: a global variable of type int commonly called "foo".
 298 )
 299
 300 static class members do not need the static_ prefix in the name (the
 301 Class::var notation usually makes it clear that it is static)
 302
 303 description(
 304 dit(code(loop_i))
 305     Variable loop: an integer
 306 dit(code(u))
 307     Temporary variable: an unsigned integer
 308 dit(code(test_ch))
 309     Variable test: a character
 310 dit(code(first_name_str))
 311     Variable first_name: a String class object
 312 dit(code(last_name_ch_a))
 313     Variable last_name: a code(char) array
 314 dit(code(foo_i_p))
 315     Variable foo: an code(Int*) that you must delete
 316 dit(code(bar_i_l))
 317     Variable bar: an code(Int*) that you must not delete
 318 )
 319
 320 Generally default arguments are taboo, except for nil pointers.
 321
 322 The naming convention can be quite conveniently memorised, by
 323 expressing the type in english, and abbreviating it
 324
 325 verb(
 326         static Array<int*> foo
 327 )
 328
 329 code(foo) can be described as "the static int-pointer user-array", so you get
 330
 331 verb(
 332         foo_static_l_arr
 333 )
 334
 335
 336
 337 nsect(MISCELLANEOUS)
 338
 339 For some tasks, some scripts are supplied, notably creating patches, a
 340 mirror of the website, generating the header to put over cc and hh
 341 files, doing a release.
 342
 343 Use them.
 344
 345 The following generic identifications are used:
 346
 347 verb(
 348         up == 1
 349         left == -1
 350         right == 1
 351         down == -1
 352 )
 353
 354 Intervals are pictured lying on a horizontal numberline (Interval[-1]
 355 is the minimum). The 2D plane has +x on the right, +y pointing up.
 356
 357