doc/RULES

   1 enigma2 python coding rules
   2 ===========================
   3
   4 1.) The Zen of Python
   5
   6 The Zen of Python, by Tim Peters
   7
   8 Beautiful is better than ugly.
   9 Explicit is better than implicit.
  10 Simple is better than complex.
  11 Complex is better than complicated.
  12 Flat is better than nested.
  13 Sparse is better than dense.
  14 Readability counts.
  15 Special cases aren't special enough to break the rules.
  16 Although practicality beats purity.
  17 Errors should never pass silently.
  18 Unless explicitly silenced.
  19 In the face of ambiguity, refuse the temptation to guess.
  20 There should be one-- and preferably only one --obvious way to do it.
  21 Although that way may not be obvious at first unless you're Dutch.
  22 Now is better than never.
  23 Although never is often better than *right* now.
  24 If the implementation is hard to explain, it's a bad idea.
  25 If the implementation is easy to explain, it may be a good idea.
  26 Namespaces are one honking great idea -- let's do more of those!
  27
  28 2.) Exceptions
  29
  30 Exceptions are great!
  31
  32 They are great to nullify any performance. Don't ever use them in functions
  33 which are called more than once or twice.
  34
  35 Don't use them when a failure is expected. Use them for unexpected failures,
  36 not as a method for coroutines.
  37
  38 C++ wrapped stuff usually doesn't throw exceptions, but returns None or
  39 stuff like that.
  40
  41 Exceptions trough C++ are evil, too. Don't throw exceptions on callbacks
  42 made from C++!
  43
  44 Exceptions are still great!
  45
  46 For example, to hide your coding errors. Don't wrap your code in a
  47 try:/except:-clause because it behaves differently each time. The proper
  48 solution is to fix your code!
  49
  50 Sometimes, exceptions are ok.
  51
  52 Really. For example, when opening a file, which you expect to be there. It's
  53 ok if there is an assertion failure, i.e. something which can't be, unless
  54 something is seriously broken (i.e. buggy, not misconfigured)!
  55
  56 As a rule of thumb,
  57
  58 "except:" (that is, without a specification which exception to catch) is
  59 generally FORBIDDEN.
  60
  61 (Of course, unless you know what you're doing. So if you're feeling smarter
  62 than this document, do whatever you like.)
  63
  64 3.) exec, eval, or other uses of dynamic code
  65
  66 Be aware that any call to exec/eval/... opens a backdoor. That sucks. Plus,
  67 it starts the parser, which is SLOOOW. There are generally very few reasons
  68 to call exec/eval.
  69
  70  - importing a "plugin", or resolving a dynamic reference (for example in a
  71    menu.xml)
  72
  73 There is __import__. "exec 'import ' + string" is not so good.
  74
  75  - dynamically resolving function names
  76
  77 There is "getattr". For example an "eval('blub.' + x)" can also be written
  78 as "blub.getattr(x)", which is a LOT faster as it doesn't need to start a
  79 parser. It's also easier to debug.
  80
  81  - dynamic code, loaded from a menu.xml.
  82
  83 You can compile() code, and call that later. The backdoor warning still
  84 applies, of course.
  85
  86 4.) formatting rules
  87
  88 Please use tabs (that is, \t) for indenting.
  89
  90 Empty lines should be either empty, or indented like the line before / line
  91 after. Empty lines are definitely preferred to save bandwidth.
  92
  93 An ascii file ends with \n, and preferrable not with other empty lines.
  94
  95 That means: make sure the last line doesn't contain any characters, thanks.
  96
  97 5.) usage of 'print'
  98
  99 While it's great to dump out debug stuff, especially if your code can crash,
 100 expect your code to be stable at some point.
 101
 102 At that point, others might get annoyed by the debug output created by your
 103 code. That's no problem, they can remove it, but they have to find them
 104 first.
 105
 106 Using "print obj" with obj being some object, preferably a complex one, is a
 107 good way to ensure that nobody is able to remove your debug output - because
 108 nobody finds it!
 109
 110 Please, always prepend something before which can be grepped. Anything, just
 111 not nothing. Going trough all prints to find the offending one is definitely
 112 no fun. Something like "print 'obj', obj" is fine. Something like "print
 113 'mySpecialPlugin actionmap is', actionMap" is even better.
 114
 115 6.-99.) Threads are bad.
 116
 117 (Unless they are worker threads. And sleep()ing is definitely not working.
 118 So if you every having a thread which sleeps, you did something wrong. There
 119 are eTimers, and not knowing how to use them is no excuse to throw aways all
 120 enigma code design concepts.)