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
  10
  11 Functions and methods do not return errorcodes, but use assert for
  12 checking status.
  13
  14 =head2 INDENTATION
  15
  16 in emacs:
  17
  18
  19         (add-hook 'c-mode-hook
  20                   '(lambda ()(setq c-basic-offset 4)))
  21
  22
  23         (add-hook 'c++-mode-hook
  24                   '(lambda() (c-set-style "Stroustrup")
  25                      )
  26                   )
  27
  28
  29 =head2 CLASSES and TYPES:
  30
  31         This_is_a_class
  32         AClass_name     (for Abbreviation_class_name)
  33
  34 =head2 DATA MEMBERS
  35
  36         Class::member
  37
  38 if the member's name resembles its type, then I use
  39
  40         class Fubular { ..}
  41
  42         Class::fubular_
  43
  44 =head2 COMMENTS
  45
  46         /// short description
  47         class Class {
  48                 ///
  49                 Data data_member_;
  50                 /**
  51                         ..
  52                 */
  53
  54                 /****************/
  55
  56                 /// short memo
  57                 member();
  58                 /**
  59                         long doco of member()
  60                 */
  61         };
  62         /**
  63                 Class documentation.
  64         */
  65
  66 Unfortunately most of the code isn't really documented that good.
  67
  68 =head2 CLASSNAMES (2)
  69
  70 A lot of classes in LilyPond start with 'P', this is to distinguish
  71 certain parts of LilyPond: the P stands for Printer, and the P-classes
  72 are supposed to be more lowlevel than the others. Example:
  73
  74 Staff uses PStaff, PScore and PCol to do the typesetting of
  75 symbols. Staff is  the "brains" for PStaff
  76
  77 NB: in PCursor (which is part of the library) P stands for PointerCursor
  78
  79
  80 =head2 MEMBERS(2)
  81
  82 Standard methods:
  83
  84         ///check that *this satisfies its invariants, abort if not.
  85         void OK() const
  86
  87         /// print *this (and substructures) to debugging log
  88         void print() const
  89
  90         /// add some data to *this;
  91         add( .. )
  92         /**
  93         Presence of these methods usually imply that it is not feasible to this
  94         via  a constructor
  95         */
  96
  97         /// replace some data of *this
  98         set( .. )
  99