Documenting your classes, methods and functions
Introduction
When you get stuck with something, there are a number of ways you can get help. When you write programs, you should always include documentation in a stardard way for your classes, methods and functions. If someone gets stuck, they can search your code for help. Python has a very powerful auto-documentation method that you should make use of.
help (xxxxx)
Imagine you have given your code for the monster class to someone else to use. How can they find out what methods it has, and what data is needed for those methods? If they type help (monster), they can get help with the monster class. We have taken the code from our previous work and removed most of the lines that print out information, but we have added help (monster) at the end. What do you think will be displayed? Here is the code that we are using now. You should modify your code so it includes a help instruction at the end of the code, as shown below.
When you run the code, apart from displaying the attributes in the monster1 and monster2 objects, it will also display all of the documentation you provided. It will tell you what the class does, what methods are available and information about each of those methods and how to use them.
You can use help for assistance with lots of different aspects of Python. For example, there are many methods associated with strings and it can be hard trying to remember them all. If you used help (str), you will get a list of all the methods a string has and how to use them. Try modifying your code. Change help (monster) to help (str) and run the code.
A standard way of producing methods and functions - the design recipe
You can put what you like in the triple quotes to document your classes, methods and functions. However, programmers like to standardise how we all do things. This helps everyone, because if we all include the same type of information, and layout the information in the same way, it becomes easier to find what we want, compared to what would be the case if we all did our own thing! Programmers in Python follow what is called the design recipe to write methods and functions. There are five parts to the design recipe.
- the header, which tells us the name and what parameters are required
- the type contract, which tells us the types of data expected, and what will be passed back
- the description, which describes what it does.
- examples, which show what will happen when certain values are supplied
- the body, which is the actual code.
For example, imagine in our game, we have to calculate something called the kh factor. We have to write a function for it. Using our design recipe, we might produce the following code:
Can you see the five parts to the design recipe?
- You can see the header on line 1.
- The type contract on line 3 tells us that this function expects two integers and will return a float.
- The description of the function is on lines 5 and 6.
- Examples are on lines 8 to 11.
- The body starts on line 14.
Wherever possible, should write code using the design recipe.
Try and do the following:
1) The area of a triangle is given by the base times the height divided by two. Using the design recipe, write a function that calculates the area. Test it.
2) Add an extra line of code to the end of the program, so that the documentation for the function is displayed. Test it works.