doc/style.py

   1 #=======================================================================
   2
   3 __version__ = '''0.1.00'''
   4 __sub_version__ = '''20080920022138'''
   5 __copyright__ = '''(c) Alex A. Naanou 2003-2007'''
   6
   7
   8 #-----------------------------------------------------------------------
   9 __doc__ = '''
  10 this module is to document the recommended coding style in this project.
  11
  12 NOTE: this is partly derived from python style PEP8 <http://python.org/peps/pep-0008.html>
  13       thus this is to be considered as a more specific extension to the PEP.
  14 NOTE: in cases not defined by this text fall back to the PEP8.
  15 NOTE: the rest of this module illustrates the styling and can be used as
  16       an example.
  17
  18
  19 General format:
  20     - code should if possible be no more than 72 chars wide.
  21     - all comments must be no more than 71 chars wide and if possible
  22       justified, unless positional commenting of very long lines of code.
  23     - all section separators must be exactly 72 chras wide.
  24
  25
  26 Commenting culture:
  27     - keep your comments current. the aim of comments is to help the
  28       user, not to confuse him (never make anyone debug your comments
  29       when what is needed is to understand your code!).
  30     - keep your comments short. write just what is relevant and do not
  31       make anyone search for what you are trying to say.
  32     - be relevant. comment on the code/task at hand and not something
  33       that is not in the direct vicinity, module or universe.
  34     - be descriptive. describe why you are doing something rather than
  35       what you are doing. the later is appropriate only if it will take
  36       more time to get it form the code than form your comment (by the
  37       average user and not by you!).
  38       making the user read the same code twice in two languages is not
  39       vary polite.
  40     - warn and instruct if needed. it is a good idea to write out all
  41       the issues that are relevant to a particular piece of code.
  42       if you have a known bug ALWAYS write it out, with all the info
  43       and references to the affected and if known the affecting code.
  44
  45
  46 Commenting style:
  47     - comments must always precede the commented code, and not follow it.
  48     - there should be no blank lines separating the comment and the
  49       commented code.
  50     - use a '#' for general commenting of code.
  51     - use '##' for temporary and commented-out code.
  52     - use '# TODO ' to indicate normal priority todo tasks/reminders.
  53     - use '# XXX ' to indicate issues of a certain priority that need
  54       to be dealt with.
  55     - High Priority Commenting (HP):
  56         - use '##!!!' for general todo markers (may not be followed by text).
  57         - use '##!!' as a start of HP remarks and notes
  58           (may be used inside comments).
  59         - use '##!! REWRITE !!##' style markers to indicate ASAP tasks/notes.
  60           use the case of the message to indicate importance.
  61           Ex:
  62             ##!! REWRITE !!##
  63             ##!! TEST !!##
  64             ##!! OPTIMIZE !!##
  65             ##!! revise !!##
  66             ...
  67     - it is recommended to avoid comments on the same line as the code.
  68       Ex:
  69           foo = 1+2 # assign to foo.
  70     - all comments must be no more than 71 chars wide and if possible justified,
  71       unless positional commenting of very long lines of code.
  72
  73
  74 Sections (outlining):
  75     - each module may be composed of different levels of sections.
  76     - a section in general may contain only one element (e.g. class, function ... etc.)
  77     - if necessary separate parts of very long class definitions into
  78       sub sections using blank lines.
  79     - group all related sections into one module or section if possible.
  80     - blank lines and sections:
  81         - each main section should end with exactly 3 blank lines.
  82         - each sub section should end with two blank lines.
  83         - the code must follow section separator directly on the next
  84           line with the exception of the declarative sections (e.g. imports,
  85           constants, data, ...etc) which should be headed by a blank line.
  86         - all definition sections (e.g. classes,  functions, ...etc)
  87           should have no blanks between the code and the section header.
  88         - if any comments, remarks or warnings need to be present for a
  89           section, they should directly follow the section separator and precede
  90           the section code.
  91     - module sections:
  92         - the first section in a file is the version and copyright info.
  93           this is obligatory, unless the module contains temporary, demo
  94           or test code.
  95         - the second section is the documentation section (this must
  96           exist in every release module).
  97         - the third section is the imports (optional).
  98         - the optional data section.
  99           NOTE: a data section should stat with a blank line.
 100         - then the module contents section.
 101         - optional test (if __name__ == '__main__') section.
 102         - the last section in the module should define editor related
 103           configuration (e.g. vim modlines ... etc.)
 104     - the section header should contain the name of the element defined within
 105       Ex:
 106         #---------------------------------------------------------ElementName---
 107         or
 108         #=======================================================================
 109         #-----------------------------------------------------------ClassName---
 110     - Section Separators:
 111         - Main sections:
 112             #-----------------------------------------------------------------------
 113             #---------------------------------------------------------ElementName---
 114
 115             #-----------------------------------------------------------------------
 116             #- - - - - - - - - - - - - - - - - - - - - - - - - - - - -ElementName- -
 117
 118             #=======================================================================
 119
 120         - Sub sections:
 121             #---------------------------------------------------------ElementName---
 122
 123             #- - - - - - - - - - - - - - - - - - - - - - - - - - - - -ElementName- -
 124
 125         - sction separators:
 126             #-----------------------------------------------------------------------
 127
 128             #- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 129
 130             #.......................................................................
 131
 132             #. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
 133
 134
 135 Element Naming Style:
 136     this is a general naming style used, note that some code dependent rules may be applied.
 137
 138     Naming by Function/Pattern:
 139         it is recommended that all elements that represent a given pattern
 140         contain the pattern name in its name
 141         Ex:
 142             class MySuperClassFramework(object):
 143                 ...
 144             or
 145             class MethodProxy(moo):
 146                 ...
 147
 148     classes:
 149         - utility
 150             a utility class is an element that is used as a function (factory) in the code.
 151             these may be all lowercase (like classmethod or staticmethod).
 152         - base/structure
 153             these are named as follows: first capital and every new word starts capital.
 154             (Ex: MyClassName)
 155
 156     public/user methods and functions:
 157         all lowercase without word separators, preferably no longer than 8 chars.
 158         if the name must be longer or is not intended to be used very often then it
 159         is acceptable to use underscores as separators.
 160         avoid long public names for often used methods/functions at all cost!
 161         (fall back to PEP8 when writing libs..)
 162
 163     variables:
 164         all lowercase names with underscore as word separator.
 165         - global constants
 166             all capital with '_' as word separator (Ex: MY_GLOBAL_CONST_VAR)
 167         - private (method)
 168             use a leading underscore '_'
 169         - private (class)
 170             use a leading underscore '_' (avoid '__' if possible due to problems with inheritance)
 171         - private (instance)
 172             use a leading underscore '_' (avoid '__' if possible due to problems with inheritance)
 173
 174
 175 General Coding Style:
 176
 177
 178 Doc Strings:
 179
 180
 181 Packages:
 182
 183
 184 Modules:
 185
 186
 187 Classes:
 188
 189
 190 Methods:
 191
 192
 193
 194
 195 Library code specifics:
 196
 197
 198
 199
 200 Release Process:
 201
 202
 203 Testing:
 204
 205
 206
 207 '''
 208
 209 #-----------------------------------------------------------------------
 210 # NOTE: the ordering of the sections shown here is not strict, though it
 211 #       is recommended to follow these guidelines:
 212 #           - data section, first private then public.
 213 #           - functions, again first private then public.
 214 #           - classes, as before private and then public.
 215 #
 216 #       a general exception is semantically organized code. then each
 217 #       separate section should follow the above guidelines.
 218 #
 219 #       but if such sections exist in a module, it is a good idea to
 220 #       ask yourself a question if it would be more logical to split
 221 #       this module into several self-contained modules or a package.
 222 #
 223 #       P.S. it is not a good idea to keep data/state as a module
 224 #       variable. constants are OK but avoid storing state in the
 225 #       library modules.
 226 #-----------------------------------------------------------------------
 227
 228 # some constants defined...
 229 CONSTAT_a = 'a'
 230 CONSTAT_B = 'B'
 231
 232
 233
 234 #-----------------------------------------------------------------------
 235 #-------------------------------------------_module_internal_function---
 236 def _module_internal_function(args):
 237     '''
 238     '''
 239     pass
 240
 241
 242
 243 #-----------------------------------------------------------------------
 244 #-----------------------------------------------------public_function---
 245 def public_function():
 246     '''
 247     '''
 248     pass
 249
 250
 251 #--------------------------------------------------------------dowork---
 252 def dowork():
 253     '''
 254     '''
 255     pass
 256
 257
 258
 259 #-----------------------------------------------------------------------
 260 #-------------------------------------------------------------MyClass---
 261 # here is an example of a class definition...
 262 class MyClass(object):
 263     '''
 264     my simple example class.
 265     '''
 266     # class private data...
 267     # some private state used here...
 268     _private_state = None
 269
 270     # class public data...
 271     # NOTE: all class level data should be documented, and avoid
 272     #       comments that simply read the next line...
 273     #       ...try to always use meaningful names.
 274     # this is something that this class will sometime use...
 275     public_something = None
 276
 277     # private methods...
 278     def _privatemethod(self):
 279         '''
 280         this method is intended for internal use or possibly for use
 281         by library extensions.
 282         '''
 283         pass
 284     def _another_nonpublic_method(self):
 285         '''
 286         here is another acceptable non-public method name.
 287         '''
 288         pass
 289
 290     # public methods...
 291     def publicmethod(self, arg1, arg2):
 292         '''
 293         and here is a good public method.
 294         '''
 295         pass
 296
 297
 298 #--------------------------------------------------------MyOtherClass---
 299 class MyOtherClass(MyClass):
 300     '''
 301     '''
 302     # MyClass interface extensions...
 303     def publicmethod(self, arg1, arg2):
 304         '''
 305         '''
 306         pass
 307
 308     # specific methods...
 309     def yetanothermethods(self):
 310         '''
 311         this name is not so good...
 312         '''
 313         pass
 314     def another_method():
 315         '''
 316         this is a better name version for the above, unless this methods
 317         is to be used often, then think of something 8-12 chars long.
 318         '''
 319         pass
 320
 321
 322
 323 #-----------------------------------------------------------------------
 324 if __name__ == '__main__':
 325     print __doc__
 326
 327
 328
 329 #=======================================================================
 330 #                                  vim:set ts=4 sw=4 nowrap expandtab :