@node Code style
@section Code style
+This section describes style guidelines for LilyPond
+source code.
+
@menu
-* Handling errors::
* Languages::
* Filenames::
* Indentation::
-* Indenting files with fixcc.py::
-* Indenting files with emacs in script mode::
-* Indenting with vim::
* Naming conventions::
* Broken code::
* Code comments::
-* Messages::
+* Handling errors::
* Localization::
@end menu
-@node Handling errors
-@subsection Handling errors
-
-As a general rule, you should always try to continue computations,
-even if there is some kind of error. When the program stops, it
-is often very hard for a user to pinpoint what part of the input
-causes an error. Finding the culprit is much easier if there is
-some viewable output.
-
-So functions and methods do not return errorcodes, they never
-crash, but report a programming_error and try to carry on.
-
-
@node Languages
@subsection Languages
file is modified, with the hope of continually improving the code.
-@node Indenting files with fixcc.py
-@subsection Indenting files with fixcc.py
+@subheading Indenting files with fixcc.py
LilyPond provides a python script that will correct the indentation
on a c++ file:
back on a line by themselves.
-@node Indenting files with emacs in script mode
-@subsection Indenting files with emacs in script mode
+@subheading Indenting files with emacs in script mode
@c email to wl@gnu.org when I get here.
Save it as a shell script, then run on the file(s) you modified.
-@node Indenting with vim
-@subsection Indenting with vim
+@subheading Indenting with vim
Although emacs indentation is the LilyPond standard, acceptable
indentation can usually be accomplished with vim. Some hints for
@node Naming conventions
@subsection Naming Conventions
+Naming conventions have been established for LilyPond
+source code.
+
@subheading Classes and Types
+Classes begin with an uppercase letter, and words
+in class names are separated with @code{_}:
+
@verbatim
This_is_a_class
@end verbatim
@subheading Macros
-Macro names should be written in uppercase completely.
+Macro names should be written in uppercase completely,
+with words separated by @code{_}:
+
+@verbatim
+THIS_IS_A_MACRO
+@end verbatim
@subheading Variables
@code{th} or @code{t}.
Multi-word variable names in C++ should have the words separated
-by the underscore character (@q{_}).
+by the underscore character (@q{_}):
+
+@verbatim
+cxx_multiword_variable
+@end verbatim
Multi-word variable names in Scheme should have the words separated
-by a hyphen (@q{-}).
+by a hyphen (@q{-}):
+@verbatim
+scheme-multiword-variable
+@end verbatim
@node Broken code
@subsection Broken code
you can not avoid it, mark the place clearly, and add a comment
explaining shortcomings of the code.
+Ideally, the comment marking the shortcoming would include
+TODO, so that it is marked for future fixing.
+
We reject broken-in-advance on principle.
understanding to make future work easier.
-@node Messages
-@subsection Messages
+@node Handling errors
+@subsection Handling errors
+
+As a general rule, you should always try to continue computations,
+even if there is some kind of error. When the program stops, it
+is often very hard for a user to pinpoint what part of the input
+causes an error. Finding the culprit is much easier if there is
+some viewable output.
+
+So functions and methods do not return errorcodes, they never
+crash, but report a programming_error and try to carry on.
-Messages need to follow Localization.
+Error and warning messages need to be localized.
@node Localization