Functions and methods do not return errorcodes, but use assert for
checking status.
+=head2 Quote:
+
+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.
+
+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 INDENTATION
in emacs:
The source is commented in the DOC++ style. Check out doc++ at
http://www.zib.de/Visual/software/doc++/index.html
+ /*
+ C style comments for multiline comments.
+ [...]
+ */
+
+
/**
short description.
Long class documentation.
+ (Hungarian postfix)
*/
class Class {
- /** short description.
+ /**
+ short description.
long description
*/
/**
short memo. long doco of member()
+ @param description of arguments
+ @return Rettype
*/
- member();
+ Rettype member(Argtype);
/// memo only
boring_member();
NB: in PCursor (which is part of the library) P stands for PointerCursor
-=head2 MEMBERS(2)
+=head2 MEMBERS (2)
Standard methods:
void print() const
/**
- protected member. Usually invoked by non-virtual A_virtual_func()
+ protected member. Usually invoked by non-virtual XXXX()
*/
- virtual do_A_virtual_func()
+ virtual do_XXXX()
/**add some data to *this.
Presence of these methods usually imply that it is not feasible to this
=head2 Hungarian
-The Hungarian Notation was conceived by
-or at least got its name from,
-the hungarian programmer x.
-It is a naming convention with the aim
-to make code more readable (for fellow programmers)
-and more accessible for programmers
-that are new to a project.
-
-The essence of the Hungarian Notation
-is that every identifier has a part
-which identifies its type
-(for functions this is the result type).
-This is particularly useful in object oriented programming,
-where a particular object implies a specific interface
-(a set of member functions, perhaps some redefined operators),
-and for accounting heap allocated memory pointers and links.
+The Hungarian Notation was conceived by or at least got its name from,
+the hungarian programmer Charles Simonyi. It is a naming convention
+with the aim to make code more readable (for fellow programmers), and
+more accessible for programmers that are new to a project.
+
+The essence of the Hungarian Notation is that every identifier has a
+part which identifies its type (for functions this is the result
+type). This is particularly useful in object oriented programming,
+where a particular object implies a specific interface (a set of
+member functions, perhaps some redefined operators), and for
+accounting heap allocated memory pointers and links.
=head2 Advantages
=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?)
remains an issue.
=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
=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<arr>
+=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<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<firstName_str>
+Variable test: a character
+
+=item C<first_name_str>
+
Variable first_name: a String class object
-=item C<first_name_ch_a>
-Variable first_name: a C<char> array
+=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<loop_i_p>
-Variable Loop: an C<Int*> that you must delete
+=item C<bar_i_l>
-=item C<loop_i_l>
-Variable Loop: an C<Int*> that you must not delete
+Variable bar: an C<Int*> that you must not delete
=back
projects / lilypond.git / blobdiff