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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Python Style Guides From Google: https://google.github.io/styleguide/pyguide.html 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”: http://legacy.python.org/dev/peps/pep-0008/ Winter 2018 CISC101 - Prof. McLeod