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         Class::member_type_()
  36
  37 the C<type> is a Hungarian notation postfix
  38
  39 =head2 COMMENTS
  40
  41 The source is commented in the DOC++ style.  Check out doc++ at
  42 F<http://www.ZIB-Berlin.DE/VisPar/doc++/doc++.html>
  43
  44         /// short description
  45         class Class {
  46                 ///
  47                 Data data_member_;
  48                 /**
  49                         ..
  50                 */
  51
  52                 /****************/
  53
  54                 /// short memo
  55                 member();
  56                 /**
  57                         long doco of member()
  58                 */
  59         };
  60         /**
  61                 Class documentation.
  62         */
  63
  64 Unfortunately most of the code isn't really documented that good.
  65
  66 =head2 CLASSNAMES (2)
  67
  68 A lot of classes in LilyPond start with 'P', this is to distinguish
  69 certain parts of LilyPond: the P stands for Printer, and the P-classes
  70 are supposed to be more lowlevel than the others. Example:
  71
  72 Staff uses PStaff, PScore and PCol to do the typesetting of
  73 symbols. Staff is  the "brains" for PStaff
  74
  75 NB: in PCursor (which is part of the library) P stands for PointerCursor
  76
  77
  78 =head2 MEMBERS(2)
  79
  80 Standard methods:
  81
  82         ///check that *this satisfies its invariants, abort if not.
  83         void OK() const
  84
  85         /// print *this (and substructures) to debugging log
  86         void print() const
  87
  88         /// add some data to *this;
  89         add( .. )
  90         /**
  91         Presence of these methods usually imply that it is not feasible to this
  92         via  a constructor
  93         */
  94
  95         /// replace some data of *this
  96         set( .. )
  97