[ << Programming work ] | [Top][Contents][Index][ ? ] | [ Release work >> ] | ||
[ < ] | [ Up : Programming work ] | [ > ] |
7.4 Code style
[ << Programming work ] | [Top][Contents][Index][ ? ] | [ Release work >> ] | ||
[ < Code style ] | [ Up : Code style ] | [ > ] |
7.4.1 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.
[ << Programming work ] | [Top][Contents][Index][ ? ] | [ Release work >> ] | ||
[ < ] | [ Up : Code style ] | [ > ] |
7.4.2 Languages
C++ and Python are preferred. Python code should use PEP 8.
[ << Programming work ] | [Top][Contents][Index][ ? ] | [ Release work >> ] | ||
[ < ] | [ Up : Code style ] | [ > ] |
7.4.3 Filenames
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 is coded in ‘class-name.*’
[ << Programming work ] | [Top][Contents][Index][ ? ] | [ Release work >> ] | ||
[ < ] | [ Up : Code style ] | [ > ] |
7.4.4 Indentation
Standard GNU coding style is used. In emacs:
(add-hook 'c++-mode-hook '(lambda() (c-set-style "gnu") ))
If you like using font-lock, you can also add this to your ‘.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)) ))
[ << Programming work ] | [Top][Contents][Index][ ? ] | [ Release work >> ] | ||
[ < ] | [ Up : Code style ] | [ > ] |
7.4.5 Classes and Types
This_is_a_class
[ << Programming work ] | [Top][Contents][Index][ ? ] | [ Release work >> ] | ||
[ < ] | [ Up : Code style ] | [ > ] |
7.4.6 Members
Member variable names end with an underscore:
Type Class::member_
[ << Programming work ] | [Top][Contents][Index][ ? ] | [ Release work >> ] | ||
[ < ] | [ Up : Code style ] | [ > ] |
7.4.7 Macros
Macro names should be written in uppercase completely.
[ << Programming work ] | [Top][Contents][Index][ ? ] | [ Release work >> ] | ||
[ < ] | [ Up : Code style ] | [ > ] |
7.4.8 Broken code
Do not write broken code. This includes hardwired dependencies, hardwired constants, slow algorithms and obvious limitations. If you can not avoid it, mark the place clearly, and add a comment explaining shortcomings of the code.
We reject broken-in-advance on principle.
[ << Programming work ] | [Top][Contents][Index][ ? ] | [ Release work >> ] | ||
[ < ] | [ Up : Code style ] | [ > ] |
7.4.9 Naming
[ << Programming work ] | [Top][Contents][Index][ ? ] | [ Release work >> ] | ||
[ < ] | [ Up : Code style ] | [ > ] |
7.4.10 Messages
Messages need to follow Localization.
[ << Programming work ] | [Top][Contents][Index][ ? ] | [ Release work >> ] | ||
[ < ] | [ Up : Code style ] | [ Debugging LilyPond > ] |
7.4.11 Localization
This document provides some guidelines for programmers write user messages. To help translations, user messages must follow uniform conventions. Follow these rules when coding for LilyPond. Hopefully, this can be replaced by general GNU guidelines in the future. Even better would be to have an English (en_BR, en_AM) guide helping programmers writing consistent messages for all GNU programs.
Non-preferred messages are marked with ‘+’. By convention, ungrammatical examples are marked with ‘*’. However, such ungrammatical examples may still be preferred.
- Every message to the user should be localized (and thus be marked for localization). This includes warning and error messages.
-
Don’t localize/gettextify:
- ‘programming_error ()’s
- ‘programming_warning ()’s
- debug strings
- output strings (PostScript, TeX, etc.)
-
Messages to be localised must be encapsulated in ‘_ (STRING)’ or
‘_f (FORMAT, ...)’. Eg:
warning (_ ("need music in a score")); error (_f ("cannot open file: `%s'", file_name));
In some rare cases you may need to call ‘gettext ()’ by hand. This happens when you pre-define (a list of) string constants for later use. In that case, you’ll probably also need to mark these string constants for translation, using ‘_i (STRING)’. The ‘_i’ macro is a no-op, it only serves as a marker for ‘xgettext’.
char const* messages[] = { _i ("enable debugging output"), _i ("ignore lilypond version"), 0 }; void foo (int i) { puts (gettext (messages i)); }
See also ‘flower/getopt-long.cc’ and ‘lily/main.cc’.
-
Do not use leading or trailing whitespace in messages. If you need
whitespace to be printed, prepend or append it to the translated
message
message (Calculating line breaks... + " ");
-
Error or warning messages displayed with a file name and line
number never start with a capital, eg,
foo.ly: 12: not a duration: 3
Messages containing a final verb, or a gerund (‘-ing’-form) always start with a capital. Other (simpler) messages start with a lowercase letter
Processing foo.ly... `foo': not declared. Not declaring: `foo'.
-
Avoid abbreviations or short forms, use ‘cannot’ and ‘do not’
rather than ‘can’t’ or ‘don’t’
To avoid having a number of different messages for the same
situation, we’ll use quoting like this ‘"message: ‘%s’"’ for all
strings. Numbers are not quoted:
_f ("cannot open file: `%s'", name_str) _f ("cannot find character number: %d", i)
-
Think about translation issues. In a lot of cases, it is better to
translate a whole message. The english grammar mustn’t be imposed
on the translator. So, instead of
stem at + moment.str () + does not fit in beam
have
_f ("stem at %s does not fit in beam", moment.str ())
-
Split up multi-sentence messages, whenever possible. Instead of
warning (_f ("out of tune! Can't find: `%s'", "Key_engraver")); warning (_f ("cannot find font `%s', loading default", font_name));
rather say:
warning (out of tune:; warning (_f ("cannot find: `%s', "Key_engraver")); warning (_f ("cannot find font: `%s', font_name)); warning (_f ("Loading default font"));
-
If you must have multiple-sentence messages, use full punctuation.
Use two spaces after end of sentence punctuation. No punctuation
(esp. period) is used at the end of simple messages.
_f ("Non-matching braces in text `%s', adding braces", text) Debug output disabled. Compiled with NPRINT. _f ("Huh? Not a Request: `%s'. Ignoring.", request)
- Do not modularise too much; words frequently cannot be translated without context. It’s probably safe to treat most occurences of words like stem, beam, crescendo as separately translatable words.
-
When translating, it is preferable to put interesting information
at the end of the message, rather than embedded in the middle.
This especially applies to frequently used messages, even if this
would mean sacrificing a bit of eloquency. This holds for original
messages too, of course.
en: cannot open: `foo.ly' + nl: kan `foo.ly' niet openen (1) kan niet openen: `foo.ly'* (2) niet te openen: `foo.ly'* (3)
The first nl message, although grammatically and stylistically correct, is not friendly for parsing by humans (even if they speak dutch). I guess we’d prefer something like (2) or (3).
- Do not run make po/po-update with GNU gettext < 0.10.35
[ << Programming work ] | [Top][Contents][Index][ ? ] | [ Release work >> ] | ||
[ < ] | [ Up : Code style ] | [ Debugging LilyPond > ] |