Documentation/CodingStyle.pod

   1 =head1 NAME
   2
   3 CodingStyle - standards while programming for LilyPond
   4
   5 =head1 DESCRIPTION
   6
   7 Please use these standards while doing programming for LilyPond
   8
   9 Functions and methods do not return errorcodes, but use assert for
  10 checking status.
  11
  12 =head2 INDENTATION
  13
  14 in emacs:
  15
  16
  17         (add-hook 'c-mode-hook
  18                   '(lambda ()(setq c-basic-offset 4)))
  19         (add-hook 'c++-mode-hook
  20                   '(lambda() (c-set-style "Stroustrup")
  21                      )
  22                   )
  23 =head2 FILES
  24
  25 The class C<This_is_a_class> is declared in F<this-is-a-class.hh> and
  26 implemented in F<this-is-a-class.cc>.
  27
  28 =head2 CLASSES and TYPES:
  29
  30         This_is_a_class
  31         AClass_name     (for Abbreviation_class_name)
  32
  33 =head2 DATA MEMBERS
  34
  35         Class::member()
  36         Type Class::member_type_
  37
  38 the C<type> is a Hungarian notation postfix for C<Type>. See below
  39
  40
  41 =head2 COMMENTS
  42
  43 The source is commented in the DOC++ style.  Check out doc++ at
  44 http://www.zib.de/Visual/software/doc++/index.html
  45
  46         /*
  47                 C style comments for multiline comments.
  48                 [...]
  49         */
  50
  51
  52         /**
  53                 short description.
  54                 Long class documentation.
  55                 (Hungarian postfix)
  56         */
  57         class Class {
  58                 /**
  59                   short description.
  60                   long description
  61                 */
  62
  63                 Data data_member_;
  64
  65
  66                 /**
  67                         short memo. long doco of member()
  68                         @param description of arguments
  69                         @return Rettype
  70                 */
  71                 Rettype member(Argtype);
  72
  73                 /// memo only
  74                 boring_member();
  75         };
  76
  77 Unfortunately most of the code isn't really documented that good.
  78
  79
  80 =head2 CLASSNAMES (2)
  81
  82 A lot of classes in LilyPond start with 'P', this is to distinguish
  83 certain parts of LilyPond: the P stands for Printer, and the P-classes
  84 are supposed to be more lowlevel than the others. Example:
  85
  86 Staff uses PStaff, PScore and PCol to do the typesetting of
  87 symbols. Staff is  the "brains" for PStaff
  88
  89 NB: in PCursor (which is part of the library) P stands for PointerCursor
  90
  91
  92 =head2 MEMBERS (2)
  93
  94 Standard methods:
  95
  96         ///check that *this satisfies its invariants, abort if not.
  97         void OK() const
  98
  99         /// print *this (and substructures) to debugging log
 100         void print() const
 101
 102         /**
 103         protected member. Usually invoked by non-virtual XXXX()
 104         */
 105         virtual do_XXXX()
 106
 107         /**add some data to *this.
 108         Presence of these methods usually imply that it is not feasible to this
 109         via  a constructor
 110         */
 111         add( .. )
 112
 113         /// replace some data of *this
 114         set( .. )
 115
 116 =head1 HUNGARIAN NOTATION NAMING CONVENTION
 117
 118 Proposed is a naming convention derived from the so-called I<Hungarian
 119 Notation>.
 120
 121 =head2 Hungarian
 122
 123 The Hungarian Notation was conceived by or at least got its name from,
 124 the hungarian programmer x.  It is a naming convention with the aim to
 125 make code more readable (for fellow programmers) and more accessible
 126 for programmers that are new to a project.
 127
 128 The essence of the Hungarian Notation is that every identifier has a
 129 part which identifies its type (for functions this is the result
 130 type).  This is particularly useful in object oriented programming,
 131 where a particular object implies a specific interface (a set of
 132 member functions, perhaps some redefined operators), and for
 133 accounting heap allocated memory pointers and links.
 134
 135 =head2 Advantages
 136
 137 Another fun quote from Microsoft Secrets:
 138
 139
 140         The Hungarian naming convention gives developers the ability
 141         to read other people's code relatively easily, with a minmum
 142         number of comments in the source code.  Jon De Vann estimated
 143         that only about 1 percent of all lines in the Excel product
 144         code consist of comments, but the code is still very
 145         understandable due to the use of Hungarian: "if you look at
 146         our source code, you also notice very few comments.  Hungarian
 147         gives us the ability to go in and read code..."
 148
 149
 150 Wow! If you use Hungarian you don't have to document your software!
 151 Just think of the hours I have wasted documenting while this "silver bullet"
 152 existed. I feel so stupid and ashamed!
 153
 154 =head2 Disadvantages
 155
 156 =over 5
 157
 158 =item *
 159 more keystrokes (disk space!)
 160
 161 =item *
 162 it looks silly C<get_slu_p()>
 163
 164 =item *
 165 it looks like code from micro suckers
 166
 167 =item *
 168 (which) might scare away some (otherwise good?)
 169 progammers, or make you a paria in the free
 170 software community
 171
 172 =item *
 173 it has ambiguities
 174
 175 =item *
 176 not very useful if not used consistently
 177
 178 =item *
 179 usefullness in I<very large>
 180 (but how many classes is very large?)
 181 remains an issue.
 182
 183 =back
 184
 185
 186
 187 =head2 Proposal
 188
 189 =over 5
 190
 191 =item *
 192 learn about cut and paste / use emacs or vi
 193 or lean to type using ten fingers
 194
 195 =item *
 196 Use emacs dabbrev-expand, with dabbrev-case-fold-search set to nil.
 197
 198 =item *
 199 use no, or pick less silly, abbrvs.
 200
 201 =item *
 202 use non-ambiguous postfixes C<identifier_name_type_modifier[_modifier]>
 203 =back
 204
 205 Macros, C<enum>s and C<const>s are all uppercase,
 206 with the parts of the names separated by underscores.
 207
 208 =head2 Types
 209
 210 =over 5
 211
 212 =item C<byte>
 213 unsigned cher. (The postfix _by is ambiguous)
 214
 215 =item C<b>
 216 bool
 217
 218 =item C<bi>
 219 bit
 220
 221 =item C<ch>
 222 char
 223
 224 =item C<f>
 225 float
 226
 227 =item C<i>
 228 signed integer
 229
 230 =item C<str>
 231 string class
 232
 233 =item C<sz>
 234 Zero terminated c string
 235
 236 =item C<u>
 237 unsigned integer
 238
 239 =back
 240
 241 =head2 User defined types
 242
 243
 244         /** Slur blah. blah.
 245         (slur)
 246         */
 247         class Slur {};
 248         Slur* slur_p = new Slur;
 249
 250 =head2 Modifiers
 251
 252 The following types modify the meaning of the prefix.
 253 These are precede the prefixes:
 254
 255 =over 5
 256
 257 =item C<a>
 258 array
 259
 260 =item C<arr>
 261 user built array.
 262
 263 =item C<c>
 264 const
 265
 266 =item C<l>
 267 temporary pointer to object (link)
 268
 269 =item C<p>
 270 pointer to newed object
 271
 272 =item C<r>
 273 reference
 274
 275 =back
 276
 277 =over 5
 278
 279 =item C<loop_i>
 280 Variable loop: an integer
 281
 282 =item C<u>
 283 Temporary variable: an unsigned integer
 284
 285 =item C<test_ch>
 286 Variable Test: a character
 287
 288 =item C<first_name_str>
 289 Variable first_name: a String class object
 290
 291 =item C<first_name_ch_a>
 292 Variable first_name: a C<char> array
 293
 294 =item C<loop_i_p>
 295 Variable Loop: an C<Int*> that you must delete
 296
 297 =item C<loop_i_l>
 298 Variable Loop: an C<Int*> that you must not delete
 299
 300 =back
 301
 302
 303