X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2FCodingStyle.pod;h=2f65fb775ebbc3235b9aa8b2d1fddc66965bbb2b;hb=8309cbcd6660ea1f0b35abacbb424ddc4158e448;hp=460935f859cab1a3a64e64636be460fd3293651c;hpb=fe3f57f573545248c6245ebeff71884c23c35a84;p=lilypond.git

diff --git a/Documentation/CodingStyle.pod b/Documentation/CodingStyle.pod
index 460935f859..2f65fb775e 100644
--- a/Documentation/CodingStyle.pod
+++ b/Documentation/CodingStyle.pod
@@ -9,6 +9,30 @@ Please use these standards while doing programming for LilyPond
 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:
@@ -34,33 +58,44 @@ in emacs:
 	Class::member()
 	Type Class::member_type_
 
-the C<type> is a Hungarian notation postfix for $C<Type>$.
+the C<type> is a Hungarian notation postfix for $C<Type>$. See below
 
 
 =head2 COMMENTS
 
 The source is commented in the DOC++ style.  Check out doc++ at
-F<http://www.ZIB-Berlin.DE/VisPar/doc++/doc++.html>
+http://www.zib.de/Visual/software/doc++/index.html
+
+	/*
+		C style comments for multiline comments.
+		[...]
+	*/
 
-	/// short description
+
+	/**
+		short description.
+		Long class documentation.
+		(Hungarian postfix)
+	*/
 	class Class {
-		///
-		Data data_member_;
 		/**
-			..
+		  short description.
+		  long description
 		*/
 
-		/****************/
+		Data data_member_;
+
 
-		/// short memo
-		member();
 		/**
-			long doco of member()
+			short memo. long doco of member()
+			@param description of arguments
+			@return Rettype
 		*/
+		Rettype member(Argtype);
+
+		/// memo only
+		boring_member();
 	};
-	/**
-		Class documentation.
-	*/
 
 Unfortunately most of the code isn't really documented that good.
 
@@ -77,7 +112,7 @@ symbols. Staff is  the "brains" for PStaff
 NB: in PCursor (which is part of the library) P stands for PointerCursor
 
 
-=head2 MEMBERS(2)
+=head2 MEMBERS (2)
 
 Standard methods:
 
@@ -87,13 +122,246 @@ Standard methods:
 	/// print *this (and substructures) to debugging log
 	void print() const
 
-	/// add some data to *this; 
-	add( .. )
 	/**
+	protected member. Usually invoked by non-virtual XXXX()
+	*/
+	virtual do_XXXX()
+
+	/**add some data to *this.
 	Presence of these methods usually imply that it is not feasible to this
 	via  a constructor
 	*/
+	add( .. )
 
 	/// replace some data of *this
 	set( .. )
 
+=head1 HUNGARIAN NOTATION NAMING CONVENTION
+
+Proposed is a naming convention derived from the so-called I<Hungarian
+Notation>.
+
+=head2 Hungarian
+
+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
+
+Another fun quote from Microsoft Secrets:
+
+
+	The Hungarian naming convention gives developers the ability
+	to read other people's code relatively easily, with a minmum
+	number of comments in the source code.  Jon De Vann estimated
+	that only about 1 percent of all lines in the Excel product
+	code consist of comments, but the code is still very
+	understandable due to the use of Hungarian: "if you look at
+	our source code, you also notice very few comments.  Hungarian
+	gives us the ability to go in and read code..."
+
+
+Wow! If you use Hungarian you don't have to document your software!
+Just think of the hours I have wasted documenting while this "silver bullet"
+existed. I feel so stupid and ashamed!
+
+=head2 Disadvantages
+
+=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.
+
+=back
+
+
+
+=head2 Proposal
+
+=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,
+with the parts of the names separated by underscores.
+
+=head2 Types
+
+=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
+
+=head2 User defined types
+
+
+	/** Slur blah. blah.
+	(slur)
+	*/
+	class Slur {};
+	Slur* slur_p = new Slur;
+
+=head2 Modifiers
+
+The following types modify the meaning of the prefix. 
+These are precede the prefixes:
+
+=over 5
+
+=item C<a>
+
+array
+
+=item C<array>
+
+user built array.
+
+=item C<c>
+
+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
+
+
+