Changes between Version 2 and Version 3 of CodingStandards


Ignore:
Timestamp:
Jul 16, 2009, 7:21:14 PM (10 years ago)
Author:
flip
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • CodingStandards

    v2 v3  
    179179  This works and is easier to read:
    180180{{{
    181 #!python 
    182  
     181#!python
    183182     z = (something * PI) - (something_else / FUDGE_FACTOR)
    184183}}}
    185184
    186 
     185{{{
     186#!rst
    187187- Don't put redundant information in names. For instance, in a Person class it
    188188  is unnecessary to call the attributes ``person_name``, ``person_address``,
     
    204204  Related note: there are files in PyVespa that have been generated by wxGlade
    205205  that contain this Python metacomment:
    206   ::
    207  
     206}}}
     207{{{
     208#!python
    208209     # -*- coding: iso-8859-15 -*-
    209 
     210}}}
     211{{{
     212#!rst
    210213  Please change this to comply with PEP 8. In practical terms, this means use
    211214  ASCII unless you need non-ASCII characters, in which case use utf-8. It'd be
     
    225228  string FIXME (no space!) in the comments and a brief explanation of what you
    226229  think is wrong. e.g.
    227   ::
    228    
     230}}}
     231{{{
     232#!python   
    229233        if film == HOLY_GRAIL:
    230234           bring_out_your_dead()
     
    234238            albatross()
    235239        # FIXME - need an else statement; how to handle unexpected cases?
    236 
    237   ..
     240}}}
     241{{{
     242#!rst
    238243
    239244C and C++
     
    291296  If you find that you're importing some package with an inconveniently long
    292297  name, make use of Python's as keyword:
    293   ::
    294  
     298}}}
     299{{{
     300#!python
    295301   import xml.etree.ElementTree as ElementTree
    296 
     302}}}
     303{{{
     304#!rst
    297305  Be mindful of creating obscure abbreviations, however:
    298   ::
    299  
     306}}}
     307{{{
     308#!python 
    300309   import some_complicated_math_library.curves.splines as sp
    301  
    302   ..
     310}}}
     311{{{
     312#!rst 
    303313
    304314- Python booleans are True and False, not 1 and 0. Be aware of this when you're
     
    313323  For instance, if a variable (received from a C function for instance) has
    314324  a value of 1 or 0 it is perfectly acceptable to do this:
    315   ::
    316  
     325}}}
     326{{{
     327#!python
    317328    if some_c_library.function_that_returns_one_or_zero():
    318329       do_something()
    319 
     330}}}
     331{{{
     332#!rst
    320333  It would be unPythonic, however, to do this:
    321   ::
    322  
     334}}}
     335{{{
     336#!python
    323337    def on_foo_checkbox_clicked():
    324338       self.foo_is_on = 1  # should be True, not 1
    325 
     339}}}
     340{{{
     341#!rst
    326342  As a specific application of duck typing, it's usually unPythonic to
    327343  explicitly test for True and
    328344  False. Note that all of these evaluate to False:
    329   ::
    330  
     345}}}
     346{{{
     347#!python
    331348        bool(None)
    332349        bool("")    # empty string
     
    335352        bool({ })   # empty dict
    336353        bool(0)
    337 
     354}}}
     355{{{
     356#!rst
    338357  All of these evaluate to True:
    339   ::
    340  
     358}}}
     359{{{
     360#!python
    341361        bool(n) where n is a non-zero number
    342362        bool(s) where s is a non-empty string
     
    344364        bool(m) where m is a non-empty mapping (dict)
    345365        bool(o) where o is an object other than None
    346 
     366}}}
     367{{{
     368#!rst
    347369  Historical note: the values True and False weren't added to Python until
    348370  sometime in the 2.x series (2.2 I think) so you might see some Python code --
     
    354376
    355377  In order to do so, we need to add this to every module that uses division:
    356   ::
    357  
     378}}}
     379{{{
     380!#python 
    358381    from __future__ import division
    359  
     382}}}
     383{{{
     384#!rst 
    360385  And then we need to review the use of division in those modules
    361386  to ensure we're not breaking them.
     
    369394  in Python 3. Our classes should always be new-style classes. To create a
    370395  new-style class, inherit from object. e.g. this:
    371   ::
    372  
     396}}}
     397{{{
     398#!python
    373399    class TransformThingy(object):
    374    
     400}}}
     401{{{
     402#!rst
    375403  not this:
    376   ::
    377  
     404}}}
     405{{{
     406#!python
    378407    class TransformThingy():
    379 
    380   ..
    381 
     408}}}
     409{{{
     410#!rst
    382411
    383412- Python has the identity operator "is". It means "are these objects the same
    384413  object" rather than "are they equivalent". The only time you'll probably need
    385414  to use it is when comparing something to None.
    386   ::
    387  
     415}}}
     416{{{
     417#!python
    388418       if foo is None:
    389419           do_something()
     420}}}
     421{{{
     422#!rst
    390423
    391424  Since we prefer to perform simple boolean tests, the need to check explicitly
    392425  for None (as opposed to False) might indicate a problem somewhere upstream, as
    393426  this would be better:
    394   ::
    395  
     427}}}
     428{{{
     429#!python
    396430      if not foo:
    397431         do_something()
     432}}}
     433{{{
     434#!rst
    398435
    399436  Sometimes an explicit test for None is unavoidable, however.
     
    408445  for taking a slice of a string from the end, try it out in the Python
    409446  interpreter:
    410   ::
    411    
     447}}}
     448{{{
     449#!python   
    412450        $ python
    413451        Python 2.5.1 (r251:54863, Nov 17 2007, 21:19:53)
     
    418456        >>>
    419457
     458}}}