Documentation/CodingStyle.texi

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