Documentation/devel/programming-work.itexi

   1 @c -*- coding: us-ascii; mode: texinfo; -*-
   2 @node Programming work
   3 @chapter Programming work
   4
   5 @menu
   6 * Introduction to programming::
   7 * Code style::
   8 @end menu
   9
  10
  11 @node Introduction to programming
  12 @section Introduction to programming
  13
  14 blah blah
  15
  16
  17 @node Code style
  18 @section Code style
  19 @c email to wl@gnu.org when I get here.
  20
  21 @menu
  22 @end menu
  23
  24 @subsection Outputting errors
  25
  26 As a general rule, you should always try to continue computations,
  27 even if there is some kind of error.  When the program stops, it
  28 is often very hard for a user to pinpoint what part of the input
  29 causes an error.  Finding the culprit is much easier if there is
  30 some viewable output.
  31
  32 So functions and methods do not return errorcodes, they never
  33 crash, but report a programming_error and try to carry on.
  34
  35 @subsection Languages
  36
  37 C++ and Python are preferred.  Python code should use PEP 8.
  38
  39 @subsection Filenames
  40
  41 Definitions of classes that are only accessed via pointers (*) or
  42 references (&) shall not be included as include files.
  43
  44 @verbatim
  45    filenames
  46
  47         ".hh"   Include files
  48              ".cc"      Implementation files
  49              ".icc"     Inline definition files
  50              ".tcc"     non inline Template defs
  51
  52    in emacs:
  53
  54              (setq auto-mode-alist
  55                    (append '(("\\.make$" . makefile-mode)
  56                         ("\\.cc$" . c++-mode)
  57                         ("\\.icc$" . c++-mode)
  58                         ("\\.tcc$" . c++-mode)
  59                         ("\\.hh$" . c++-mode)
  60                         ("\\.pod$" . text-mode)
  61                         )
  62                       auto-mode-alist))
  63 @end verbatim
  64
  65 The class Class_name is coded in @q{class-name.*}
  66
  67 @subsection Indentation
  68
  69 Standard GNU coding style is used. In emacs:
  70
  71 @verbatim
  72              (add-hook 'c++-mode-hook
  73                   '(lambda() (c-set-style "gnu")
  74                      ))
  75 @end verbatim
  76
  77 If you like using font-lock, you can also add this to your
  78 @q{.emacs}:
  79
  80 @verbatim
  81              (setq font-lock-maximum-decoration t)
  82              (setq c++-font-lock-keywords-3
  83                    (append
  84                     c++-font-lock-keywords-3
  85                     '(("\\b\\(a-zA-Z_?+_\\)\\b" 1 font-lock-variable-name-face) ("\\b\\(A-Z?+a-z_?+\\)\\b" 1 font-lock-type-face))
  86                     ))
  87 @end verbatim
  88
  89
  90 @subsection Classes and Types
  91
  92 @verbatim
  93              This_is_a_class
  94 @end verbatim
  95
  96
  97 @subsection Members
  98
  99 Member variable names end with an underscore:
 100
 101 @verbatim
 102      Type Class::member_
 103 @end verbatim
 104
 105
 106 @subsection Macros
 107
 108 Macro names should be written in uppercase completely.
 109
 110
 111 @subsection Broken code
 112
 113 Do not write broken code.  This includes hardwired dependencies,
 114 hardwired constants, slow algorithms and obvious limitations.  If
 115 you can not avoid it, mark the place clearly, and add a comment
 116 explaining shortcomings of the code.
 117
 118 We reject broken-in-advance on principle.
 119
 120 @subsection Naming
 121
 122
 123 @subsection Messages
 124
 125 Messages need to follow Localization.
 126
 127
 128 @subsection Localization
 129
 130 This document provides some guidelines for programmers write user
 131 messages.  To help translations, user messages must be
 132 uniformized.  Follow these rules when coding for LilyPond.
 133 Hopefully, this can be replaced by general GNU guidelines in the
 134 future.  Even better would be to have an English (en_BR, en_AM)
 135 helping programmers writing consistent messages for all GNU
 136 programs.
 137
 138 Not-preferred messages are marked with `+'. By convention,
 139 ungrammatical examples are marked with `*'.
 140
 141 @itemize
 142
 143 @item
 144 Every message to the user should be localised (and thus be marked
 145 for localisation). This includes warning and error messages.
 146
 147 @item
 148 Don't localise/gettextify:
 149
 150 @itemize
 151 @item
 152 `programming_error ()'s
 153
 154 @item
 155 `programming_warning ()'s
 156
 157 @item
 158 debug strings
 159
 160 @item
 161 output strings (PostScript, TeX, etc.)
 162
 163 @end itemize
 164
 165 @item
 166 Messages to be localised must be encapsulated in `_ (STRING)' or
 167 `_f (FORMAT, ...)'. Eg:
 168
 169 @verbatim
 170       warning (_ ("need music in a score"));
 171       error (_f ("cannot open file: `%s'", file_name));
 172 @end verbatim
 173
 174 In some rare cases you may need to call `gettext ()' by hand. This
 175 happens when you pre-define (a list of) string constants for later
 176 use. In that case, you'll probably also need to mark these string
 177 constants for translation, using `_i (STRING)'. The `_i' macro is
 178 a no-op, it only serves as a marker for `xgettext'.
 179
 180 @verbatim
 181       char const* messages[] = {
 182       _i ("enable debugging output"),
 183       _i ("ignore lilypond version"),
 184       0
 185       };
 186
 187
 188       void
 189       foo (int i)
 190       {
 191       puts (gettext (messages i));
 192       }
 193 @end verbatim
 194
 195 See also `flower/getopt-long.cc' and `lily/main.cc'.
 196
 197 @item
 198 Do not use leading or trailing whitespace in messages. If you need
 199 whitespace to be printed, prepend or append it to the translated
 200 message
 201
 202 @verbatim
 203       message (Calculating line breaks... + " ");
 204 @end verbatim
 205
 206 @item
 207 Error or warning messages displayed with a file name and line
 208 number never start with a capital, eg,
 209
 210 @verbatim
 211         foo.ly: 12: not a duration: 3
 212 @end verbatim
 213
 214 Messages containing a final verb, or a gerund (`-ing'-form) always
 215 start with a capital. Other (simpler) messages start with a
 216 lowercase letter
 217
 218 @verbatim
 219       Processing foo.ly...
 220       `foo': not declared.
 221       Not declaring: `foo'.
 222 @end verbatim
 223
 224 @item
 225 Avoid abbreviations or short forms, use `cannot' and `do not'
 226 rather than `can't' or `don't'
 227 To avoid having a number of different messages for the same
 228 situation, we'll use quoting like this `"message: `%s'"' for all
 229 strings. Numbers are not quoted:
 230
 231 @verbatim
 232       _f ("cannot open file: `%s'", name_str)
 233       _f ("cannot find character number: %d", i)
 234 @end verbatim
 235
 236 @item
 237 Think about translation issues. In a lot of cases, it is better to
 238 translate a whole message. The english grammar mustn't be imposed
 239 on the translator. So, instead of
 240
 241 @verbatim
 242       stem at  + moment.str () +  does not fit in beam
 243 @end verbatim
 244
 245 have
 246
 247 @verbatim
 248       _f ("stem at %s does not fit in beam", moment.str ())
 249 @end verbatim
 250
 251 @item
 252 Split up multi-sentence messages, whenever possible. Instead of
 253
 254 @verbatim
 255       warning (_f ("out of tune!  Can't find: `%s'",
 256 "Key_engraver"));
 257       warning (_f ("cannot find font `%s', loading default",
 258       font_name));
 259 @end verbatim
 260
 261 rather say:
 262
 263 @verbatim
 264       warning (out of tune:;
 265       warning (_f ("cannot find: `%s', "Key_engraver"));
 266       warning (_f ("cannot find font: `%s', font_name));
 267       warning (_f ("Loading default font"));
 268 @end verbatim
 269
 270 @item
 271 If you must have multiple-sentence messages, use full punctuation.
 272 Use two spaces after end of sentence punctuation. No punctuation
 273 (esp. period) is used at the end of simple messages.
 274
 275 @verbatim
 276       _f ("Non-matching braces in text `%s', adding braces", text)
 277       Debug output disabled.  Compiled with NPRINT.
 278       _f ("Huh?  Not a Request: `%s'.  Ignoring.", request)
 279 @end verbatim
 280
 281 @item
 282 Do not modularise too much; a lot of words cannot be translated
 283 without context. It's probably safe to treat most occurences of
 284 words like stem, beam, crescendo as separately translatable words.
 285
 286 @item
 287 When translating, it is preferable to put interesting information
 288 at the end of the message, rather than embedded in the middle.
 289 This especially applies to frequently used messages, even if this
 290 would mean sacrificing a bit of eloquency. This holds for original
 291 messages too, of course.
 292
 293 @verbatim
 294       en: cannot open: `foo.ly'
 295       +   nl: kan `foo.ly' niet openen (1)
 296       kan niet openen: `foo.ly'*   (2)
 297       niet te openen: `foo.ly'*    (3)
 298 @end verbatim
 299
 300
 301 The first nl message, although grammatically and stylistically
 302 correct, is not friendly for parsing by humans (even if they speak
 303 dutch). I guess we'd prefer something like (2) or (3).
 304
 305 @item
 306 Do not run make po/po-update with GNU gettext < 0.10.35
 307
 308 @end itemize
 309
 310
 311