=head1 NAME
-CodingStyle - standards while programming for LilyPond
+CodingStyle - standards while programming for GNU LilyPond
=head1 DESCRIPTION
-Please use these standards while doing programming for LilyPond
+Please use these standards while doing programming for GNU LilyPond
Functions and methods do not return errorcodes, but use assert for
checking status.
- A program should be light and agile, its subroutines
- connected like a strings of pearls. The spirit and intent of
- the program should be retained throughout. There should be
- neither too little nor too much, neither needless loops nor
- useless variables, neither lack of structure nor overwhelming
- rigidity.
+=head2 Quote:
- A program should follow the 'Law of Least
- Astonishment'. What is this law? It is simply that the
- program should always respond to the user in the way that
- astonishes him least.
+A program should be light and agile, its subroutines
+connected like a string of pearls. The spirit and intent of
+the program should be retained throughout. There should be
+neither too little nor too much, neither needless loops nor
+useless variables, neither lack of structure nor overwhelming
+rigidity.
- A program, no matter how complex, should act as a
- single unit. The program should be directed by the logic
- within rather than by outward appearances.
+A program should follow the 'Law of Least
+Astonishment'. What is this law? It is simply that the
+program should always respond to the user in the way that
+astonishes him least.
+
+A program, no matter how complex, should act as a
+single unit. The program should be directed by the logic
+within rather than by outward appearances.
+
+If the program fails in these requirements, it will be
+in a state of disorder and confusion. The only way to correct
+this is to rewrite the program.
+
+-- Geoffrey James, "The Tao of Programming"
+
+=head2 FILES
+
+Definitions of classes that are only accessed via pointers
+(*) or references (&) shall not be included as include files.
+
+filenames
+
+ ".hh" Include files
+ ".cc" Implementation files
+ ".icc" Inline definition files
+ ".tcc" non inline Template defs
+
+in emacs:
+
+ (setq auto-mode-alist
+ (append '(("\\.make$" . makefile-mode)
+ ("\\.cc$" . c++-mode)
+ ("\\.icc$" . c++-mode)
+ ("\\.tcc$" . c++-mode)
+ ("\\.hh$" . c++-mode)
+ ("\\.pod$" . text-mode)
+ )
+ auto-mode-alist))
+
+
+The class Class_name_abbreviation is coded in F<class-name-abbr.*>
- If the program fails in these requirements, it will be
- in a state of disorder and confusion. The only way to correct
- this is to rewrite the program.
- -- Geoffrey James, "The Tao of Programming"
=head2 INDENTATION
)
)
+If you like using font-lock, you can also add this to your F<.emacs>:
+
+ (setq font-lock-maximum-decoration t)
+ (setq c++-font-lock-keywords-3
+ (append
+ c++-font-lock-keywords-3
+ '(("\\b\\([a-zA-Z_]+_\\)\\b" 1 font-lock-variable-name-face)
+ ("\\b\\([A-Z]+[a-z_]+\\)\\b" 1 font-lock-type-face))
+ ))
=head2 CLASSES and TYPES:
Class::member()
Type Class::member_type_
-the C<type> is a Hungarian notation postfix for $C<Type>$. See below
+the C<type> is a Hungarian notation postfix for C<Type>. See below
+=head2 BROKEN CODE
+
+Broken code (hardwired dependencies, hardwired constants, slow
+algorithms and obvious limitations) should be marked as such:
+either with a verbose TODO, or with a short "ugh" comment.
+
=head2 COMMENTS
The source is commented in the DOC++ style. Check out doc++ at
/*
C style comments for multiline comments.
+ They come before the thing to document.
[...]
*/
short description.
Long class documentation.
(Hungarian postfix)
+
+ TODO Fix boring_member()
*/
class Class {
/**
Rettype member(Argtype);
/// memo only
- boring_member();
+ boring_member() {
+ data_member_ = 121; // ugh
+ }
};
-Unfortunately most of the code isn't really documented that good.
-
-=head2 CLASSNAMES (2)
-
-A lot of classes in LilyPond start with 'P', this is to distinguish
-certain parts of LilyPond: the P stands for Printer, and the P-classes
-are supposed to be more lowlevel than the others. Example:
-
-Staff uses PStaff, PScore and PCol to do the typesetting of
-symbols. Staff is the "brains" for PStaff
-
-NB: in PCursor (which is part of the library) P stands for PointerCursor
+
+Unfortunately most of the code isn't really documented that good.
-=head2 MEMBERS(2)
+=head2 MEMBERS (2)
Standard methods:
=over 5
=item *
+
more keystrokes (disk space!)
=item *
+
it looks silly C<get_slu_p()>
=item *
+
it looks like code from micro suckers
=item *
+
(which) might scare away some (otherwise good?)
progammers, or make you a paria in the free
software community
=item *
+
it has ambiguities
=item *
+
not very useful if not used consistently
=item *
-usefullness in I<very large>
-(but how many classes is very large?)
+
+usefullness in I<very large> (but how many classes is very large?)
remains an issue.
=back
=over 5
=item *
+
learn about cut and paste / use emacs or vi
or lean to type using ten fingers
=item *
+
Use emacs dabbrev-expand, with dabbrev-case-fold-search set to nil.
=item *
+
use no, or pick less silly, abbrvs.
=item *
+
use non-ambiguous postfixes C<identifier_name_type_modifier[_modifier]>
+
=back
Macros, C<enum>s and C<const>s are all uppercase,
=over 5
=item C<byte>
+
+
unsigned char. (The postfix _by is ambiguous)
=item C<b>
+
+
bool
=item C<bi>
+
bit
=item C<ch>
+
char
=item C<f>
+
float
=item C<i>
+
signed integer
=item C<str>
+
string class
=item C<sz>
+
Zero terminated c string
=item C<u>
+
unsigned integer
=back
=over 5
=item C<a>
+
array
=item C<array>
+
user built array.
=item C<c>
-const
+
+const. Note that the proper order C<Type const> i.s.o. C<const Type>
+
+=item C<C>
+
+A const pointer. This would be equivalent to C<_c_l>, but since any
+"const" pointer has to be a link (you can't delete a const pointer),
+it is superfluous.
=item C<l>
+
temporary pointer to object (link)
=item C<p>
+
pointer to newed object
=item C<r>
+
reference
=back
=over 5
=item C<loop_i>
+
Variable loop: an integer
=item C<u>
+
Temporary variable: an unsigned integer
=item C<test_ch>
+
Variable test: a character
=item C<first_name_str>
+
Variable first_name: a String class object
=item C<last_name_ch_a>
+
Variable last_name: a C<char> array
=item C<foo_i_p>
+
Variable foo: an C<Int*> that you must delete
=item C<bar_i_l>
+
Variable bar: an C<Int*> that you must not delete
=back
+Generally default arguments are taboo, except for nil pointers.
+
+=head1 MISCELLANEOUS
+
+For some tasks, some scripts are supplied, notably creating patches, a
+mirror of the website, generating the header to put over cc and hh
+files, doing a release.
+
+Use them.
+
+The following generic identifications are used:
+
+ up == 1
+ left == -1
+ right == 1
+ down == -1
+
+Intervals are pictured lying on a horizontal numberline (Interval[-1]
+is the minimum). The 2D plane has +x on the right, +y pointing up.
projects / lilypond.git / blobdiff