Documenting a function Documenting a function definition We

Documenting a function

Documenting a function definition • We have a template for information that we need you to put at the top of each function - if you do this as part of your design, you will be ready when you write the implementation • The name of the function • The purpose of the function • The preconditions = the parameters – their meaning, not just how many there are! Also include types that are allowed / expected. If a user is asked for input in the function, mention that also (later, if the function reads from a file, mention that too!) • The postconditions = the return value(s) (their meanings and types) and/or output. Also if a function creates a data file, mention that also. • The design

Example: ‘’’ function draw_circle purpose: draws the circle with specified size and outline color on the graphics window, using the Zelle graphics library preconditions: x and y of center of circle, radius of circle, color of line to draw with, and graphwin object to display circle on postconditions: nothing returned, circle as specified drawn on given window Design 1. Create circle object with point and radius provided 2. Set the color of the circle outline to given color 3. Draw the circle on the graphics window ‘’’

A docstring • Some people and software companies have a standard requirement of putting all this information in a triply-quoted string at the very top of the function. • It’s called a “docstring” in that case • Some software that professionals use can actually pull out those comments to produce documentation for their company • In this class it’s up to you whether you use the ‘’’ or the # to make these comments • Of course, you put your implementation between the lines of design comments, as usual, when writing the Python code