Style:Declarations

From 6.00 reference wiki

Elements of Style for Python Programmers: Main | Names | Variable Declarations | Indentation | Exceptions

Declare every variable’s type and meaning.

Every variable should have a declaration that states its type (the set of values it can take). Many times it is also a good idea to give some indication of its meaning (what it’s used for). Since Python has no direct support for variable declarations, this declaration should take the form of a comment. For example:

     # hyp: float (hypotenuse of triangle)

This declaration says that hyp is a floating-point variable that represents the hypotenuse of a triangle. Here are other examples:

     # n: integer
     # inputOK: boolean (True if input was read without error)
     # names: list of strings  (names of the students in alphabetical order)
     # val: anything (value entered by the user)

Declarations for related variables should be grouped together, above the code where the variable first appears.

[edit]

Declare every function’s purpose and arguments.

Every function should have a declaration that describes the type and meaning of each formal argument, plus the type and meaning of the value that the function returns. If the function makes any assumptions – e.g., that one of its arguments must be positive, or that a list must be sorted – then these assumptions must be included in the declaration.

Python has a special convention called a documentation string that allows the declaration to be retrieved by calling help(). A documentation string must be the first line of the function (after the def line), and it should be surrounded by three double-quote marks """. (Unlike ordinary double-quotes, triple double-quotes allow you to put line breaks into the string).

For example:

     def factorial(n):
         """n: int >= 0
             returns n!"""
         if n == 0:
             return 1
         else:
             return n*factorial(n-1)

The documentation string can be retrieved by calling help() and will pop-up in IDLE as you type:

     >>> help(factorial)
     Help on function factorial in module __main__: 
     factorial(n)
         n: integer >= 0
         returns n!

Here are other examples of properly documented functions:

     def deposit(account, amount):
         """deposits money into an account
                account: Account to receive the deposit
                amount: int (money in dollars)
                returns amount deposited, or None if account has been closed"""

Here, we have used int as short-hand for integer.

[edit]

Declare and initialize all global variables at the top of the program.

If you use a global variable, put its declaration at the top of your program, and make sure you give it an initial value there too:

     # screenName: string (the user’s AIM screen name)
     screenName = None

The initialization ensures that the global variable exists, which eliminates a potential pitfall. Otherwise, Python may think you want to create a local variable when you write to the global variable later, e.g.:

     def setScreenName(name):
         """name: string (the user’s AIM screen name) 
                    sets the user’s screen name """
         screenName = name

Without the initialization, Python will create a local variable called screenName, which will disappear as soon as the setScreenName function is finished.

Retrieved from "http://slice.csail.mit.edu../../../d/e/c/Style%7EDeclarations_30b2.html"

This page has been accessed 45 times. This page was last modified 11:40, 6 February 2006 by 6.00 reference wiki user Asfandyar.