1. Winter 2018 CISC101
11/27/2018
CISC101 Reminders
Quiz 1 this week. More info in last Tuesday’s lecture.
Assn 1 now due Monday, Feb. 5, next week.
Exercise 3 is fair game now – conditionals.
Winter 2018
CISC101 - Prof. McLeod
Prof. Alan McLeod

2. Today Style Applicable to Simple Programs. Demo Programs. Winter 2018
CISC101 - Prof. McLeod

3. Commenting Code
An important part of how you will make your code more readable for yourself and anyone else (your grader!) who has to read your code.
But, where to put comments, and how much commenting is enough?
Winter 2018
CISC101 - Prof. McLeod

4. Programming Style & Documentation
CISC101
Programming Style & Documentation
Purpose is to make your code readable (and “debuggable”) by you or another programmer who is familiar with the language you are using:
“Code is read more often than it is written.”
(Guido van Rossum)
Internal style elements are documentation (comments), spacing, and descriptive variable names.
Select the conventions you want to use and be consistent.
Winter 2018
CISC101 - Prof. McLeod
Prof. Alan McLeod

5. Comments
Add a block comment to the top of the module (your program) and at the beginning of each function. Describe overall purpose of your program or function, the main algorithm used, author, date created, and any assumptions made and/or bugs found.
Function comments should state what parameters are expected by the function and what the function returns, if anything. Function comments should also state any assumptions made about the state of the arguments.
Winter 2018
CISC101 - Prof. McLeod

6. Documentation Strings
CISC101
Documentation Strings
If you put a string literal right after the def … statement it is a documentation string.
It will be regurgitated by the help system and can be accessed using special variables.
You can use triple quotes to place a large document here!
Used mostly when creating object definitions (classes).
Still - not a bad habit to get into…
Winter 2018
CISC101 - Prof. McLeod
Prof. Alan McLeod

7. Documentation Strings, Cont.
If you describe your function in a doc string you don’t need as much in a block comment above the def fcn() : line.
What would you not include in a doc string?
Author of function.
Date/revision number.
Code history.
Problem areas.
Incomplete section(s).
License/copyright, etc.
Winter 2018
CISC101 - Prof. McLeod

8. Comments, Cont.
Add in-line comments for variables when first initialized, when the name of variable is not self-explanatory.
Add comments at the beginnings of logical blocks of code. Indent comment same as start of block.
You don’t need to explain code that is obvious – just focus on code that is tricky to understand (maybe it needs to be re-written?).
# TODO comments can be used to mark where more work is needed.
Winter 2018
CISC101 - Prof. McLeod

9. Aside - Commenting During Development
In addition to the # TODO comment:
You can temporarily remove a chunk of code that you may not need, but don’t want to completely delete by:
Selecting the lines of code, and
Choosing “Format” from the menu bar, followed by
“Comment Out Region”.
(Or use <Alt>3)
You can also “Un-Comment Out” the region. (Use <Alt>4)
However, don’t leave these chunks in your final program version…
Winter 2018
CISC101 - Prof. McLeod

10. Commenting, Example See ClothesCommented.py
You do not have to have doc strings in your assignment 1 code.
Winter 2018
CISC101 - Prof. McLeod

11. CISC101
Another Demo Program
See another example program called WindowWeight.py.
It calculates the weight of a piece of window glass given its dimensions.
Winter 2018
CISC101 - Prof. McLeod
Prof. Alan McLeod

12. Features Use of global constants. Good commenting style.
Use of a doc string.
Error checking.
Winter 2018
CISC101 - Prof. McLeod

13. CISC101
Variable Scope
A variable created inside a function is known only inside that function.
A variable created at the same level as the function headers is known everywhere in the program. These variables are called “global variables”.
What do I mean by “known”?
Winter 2018
CISC101 - Prof. McLeod
Prof. Alan McLeod

14. Global Variables Simple rules:
Don’t declare global variables unless the majority of your functions will use this variable and you think your code will be easier to work with and read as a result.
You can declare constants as global variables. By convention, the constant’s variable name should be in all upper case.
Winter 2018
CISC101 - Prof. McLeod

15. Aside - “Magic Numbers”
These are numeric literals that just appear in your program.
Sometimes they make sense, like assigning:
sum = 0
But, sometimes they don’t:
distance = measurement / 2.54
What is this number 2.54? Where did it come from and what does it mean?
Better:
distance = measurement / CM_PER_INCH
Winter 2018
CISC101 - Prof. McLeod

16. Style, Cont. - Spacing
Use a tab that generates 4 spaces for indentation.
Don’t mix tabs and spaces (not a problem if you are only using IDLE. When you hit the <tab> key you automatically get 4 spaces.)
Long lines:
Keep lines < 80 characters in length.
Use the Python continuation character: \
Break a line after a binary operator, not before.
Indent a continued line so that it lines up as shown by the examples on the next slide:
Winter 2018
CISC101 - Prof. McLeod

17. Spacing, Cont. Continuation examples:
longAssignment = aLongName + anotherLongName - \
anotherVariable * 2.0
returnedVal = functionCall(param1, anotherParam, \
param2, param3)
Don’t put multiple lines of code on a single line. For example:
if bingo < 3 : bork = try + again
else : we = are + all + winners
Winter 2018
CISC101 - Prof. McLeod

18. Spacing, Cont. Blank Lines:
Use one blank line above a def statement - no blank lines below.
A blank line inside a function can be used to delineate a block of code, but don’t put too many blank lines inside a function. (Don’t double space your code!!)
Winter 2018
CISC101 - Prof. McLeod

19. Spacing, Cont. Spaces: space on both sides of a :
(Google style says no space on the left of a : )
space after a comma, but not before.
spaces on both sides of a binary operator.
spaces on both sides of keywords like in, not in, is, and, or, not.
No space after a unary operator.
Don’t use spaces around a = when used in a function’s parameter list (default and keyword arguments).
Winter 2018
CISC101 - Prof. McLeod

20. Spacing, Cont. Spaces and brackets:
No space before or after ( and ) unless an operator comes before or after the brackets.
Same rules for [ ] and { }.
Winter 2018
CISC101 - Prof. McLeod

21. Using Round Brackets
Don’t use round brackets when they are not necessary. For example, don’t do:
if (x > 2): while (x < 3): if not(x): if ((x < 3) and (not y)): return (foo) Understanding precedence will help!
Winter 2018
CISC101 - Prof. McLeod

22. Misc. No code after a : when it is used with a def, if or while loop.
Define main at the top of your program or at the end - not in the middle!
One import statement per line.
Put import statements before globals but after block comments and module-level doc strings.
(There is a big set of additional rules for doc strings themselves that I won’t get into here…)
Winter 2018
CISC101 - Prof. McLeod

23. Do # This program is used to demonstrate better style.
# Version 1, by Alan McLeod, 27 Oct. 2011
def product(num1, num2) :
'''This is a useless little function that does not do much'''
print('Hello')
return num1 * num2
def main() :
'''main invokes product and then waves goodbye!'''
print(product(3, 4))
print('Goodbye!')
main()
Winter 2018
CISC101 - Prof. McLeod

24. Don’t! This works! How many things are wrong with this code?
def m(ll1,l1):print('Hello');return(ll1*l1);
def main():print(m(3,4));print("Goodbye!")
main ()
This works!
How many things are wrong with this code?
Winter 2018
CISC101 - Prof. McLeod

25. Python Style Guides From Google:
Lots of detail – more than you need, right now.
Originally intended for internal use (Google uses Python a lot – or at least, they used to…).
At python.org, “PEP 8”:
Winter 2018
CISC101 - Prof. McLeod