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