Organising, Testing and Documenting Python Code

Hello students, welcome to Kwickprep. Your program works today. But in one month, will you still understand it? Today we will learn to split code into functions and modules, follow naming rules, write helpful docstrings, and test code with assert.

A long program written as one big block is hard to manage. Organised code is easy to read, for you and for your friends. When something breaks, you can find the mistake quickly. You write a piece once and reuse it many times. And you can test each small part on its own.

A function is a named block of code that does one job. The list m holds three marks. Here, total adds all the marks, using the sum function. Grade takes a total, called t, and gives A if it is at least two hundred forty, else B. Each function does exactly one job. The total is two hundred forty, so it prints two hundred forty and A.

Pause and predict. What if the last mark is eighty nine instead of ninety? The total becomes two hundred thirty nine. Is two hundred thirty nine greater than or equal to two hundred forty? No, so the grade is B. Always test the value right on the edge, because bugs love to hide there.

When a program grows, even functions are not enough. A module is simply a Python file, ending in dot pie, full of code. You already use modules made by others, like math and random. You can put related functions in your own file, for example a file called marks dot pie. Then any other program can import that file, and use its functions.

Normally you create marks dot pie in your editor. So this example runs on its own, the first two lines write that file from code. They put one function, add, into marks dot pie. The next two lines tell Python to also look for modules in the current folder. Now, import marks loads the file. We call marks dot add, and it prints two hundred forty.

Every Python file has a hidden variable called dunder name. When you run the file directly, dunder name holds the text dunder main. When another program imports the file, dunder name holds the file's name instead. So the if line means, run this part only when the file is run directly. The test code runs here and prints two hundred forty, but an import would stay quiet.

Pep 8 is the official style guide for Python code, and pep means Python Enhancement Proposal. Variables and functions use snake case, which means small letters joined by underscores. Classes use CapWords, where every word starts with a capital. Constants, values that never change, use all capital letters. And every indent uses four spaces.

Here the rules are followed. A name like x or g p would tell the reader nothing. Get percent and total marks explain themselves. Max marks is in capitals, because it is a constant. ReportCard is a class, so it uses CapWords. Star means multiply and slash means divide. Four hundred thirty out of five hundred gives eighty six point zero percent.

Pep 8 has a few more simple habits. Put one space around operators like equals and plus, and after every comma. Keep each line short, at most seventy nine characters. Leave two blank lines between functions at the top level of a file. On our slides we skip those blank lines to save space. Most of all, choose names that say what they hold.

A docstring is a short note written in triple quotes, as the very first line inside a function. It says what the function does. Unlike a normal comment, Python keeps it. Dot, dunder doc, shows it, and the help function shows it too. Area of five and four gives twenty.

A comment starts with a hash sign, and Python ignores it. A bad comment repeats the code, like, sort the list. A good comment explains why, like the school rule of dropping the lowest test. Sorted puts the marks in order. The slice from one onwards skips the first, lowest mark. So it prints seventy two, eighty eight and ninety five.

A test is code that checks other code. The assert statement checks a condition. Double equals asks, are both sides equal? If the answer is True, nothing happens and the program moves on. Forty five out of fifty is ninety percent, and zero out of fifty is zero. Both tests pass, so the last line prints All tests passed.

When the condition is False, assert raises an AssertionError, with the message after the comma. Here, try and except catch that error, so we can print it. The average of eighty and sixty should be seventy. But division happens before addition, so the function gives eighty plus thirty, which is one hundred ten. The test caught the bug, and brackets around a plus b fix it.

Here are four habits for good tests. Test normal values, the kind you expect every day. Test edge values too, like zero, full marks, and exactly the pass mark. Run all your tests again after every change, so old parts do not break silently. And use assert only for checking your own code, never for checking what a user types, because Python can switch asserts off.

Let us revise what we learned today. Functions each do one job, and modules group related functions into files. Pep 8 asks for snake case, CapWords for classes, capitals for constants, and four spaces. Docstrings say what a function does. Good comments explain why, not what. And assert checks your code, raising an AssertionError when the condition is False.