reveal.js

# Documenting Functions

---

CS 65 // 2021-02-25

## Extra Credit Activities
- [Songs for A New World](https://calendar.drake.edu/event/songs_for_a_new_world?utm_campaign=widget&utm_medium=widget&utm_source=Drake+University+Calendar) Livestream Performance
    + Thursday, 2/25 from 8:00 to 10:00pm
- [Global Citizen Forum](https://www.drake.edu/diversity/initiatives/globalcitizenforum2021/)
    + Conference on equity and inclusion in higher ed
    + March 3-5

# Exam 1 Debrief

# Assignment 4
- Will be posted later today
- It is a **group** assignment
- Your partner today is your partner for the assignment

# Code of Conduct

## Code of Conduct
- An overwhelming majority of groups proposed to **adopt** Wray's driver/navigator method

## Code of Conduct
- Main themes from your proposals
    + 
 Communication
    + 
 Respect / professionalism
    + 
 Be prepared / stay focused
    + 
 Encouragement
- 
 Consequences for violations
    + 
 Many of you pointed out that it **depends**
    + 
 Huge variation of severity depending on the circumstance

# Questions
## ...about anything?

# Self Checks
## ...from the Functions Reading

# Comments and Documentation

## Commenting Code
- Recall that a **comment** in Python is a line of code that includes a `#` symbol

```py
# Finds the distance between points (x1, y1) and (x2, y2)
dist = math.sqrt((x1-x2)**2 + (y1-y2)**2)
```

---

- 
 **Discuss** with your partner:
    + Why are comments useful?
    + When should we include comments in our code?

## Commenting Code
> Why are comments useful?
 
---

- Let's you "say what you're thinking"
    + So when other people are reading your code, you can tell them why you wrote it that way
- Can explain "why" something is implemented the way it is

## Commenting Code
> When should we comment our code?

---

- Should put comments whenever you need to explain something that is complex

## Documenting Code
- It is easy to forget what a function does
- In these cases, we often need to look up **documentation** for the function to see how it works
- 
 In Thonny you can get documentation for a function using the **help** function:

```text
>>> help(round)
round(...)
    round(number[, ndigits]) -> number
    Round a number to a given precision in decimal digits
    (default 0 digits). This returns an int when called with
    one argument, otherwise the same type as the number.
    ndigits may be negative.
```

## Documenting Code
- **Discuss** with your partner:
    + Why is documentation useful?
    + When should we write documentation for our code?

## Documenting Code
> Why is documentation useful?

---

- Documenting code that you use frequently is helpful
    + Can come back and use it!
- To help someone know what parameters are needed for a function and what each of them are for

## Documenting Code
> When should we write documentation?

---

- Regularly document things
- Use it on complex functions
- Whenever you have a public library or code that is going to be used externally

## Writing Documentation
- When using a function, we often want to know:
    1. What is the **purpose** of the function?
    2. 
 What **parameters** does the function take?
    3. 
 What does it **return**?
    4. 
 What are its **preconditions**?
        + i.e. conditions that must be met before calling the function---if these aren't met the function may fail
    5. 
 What are its **postconditions**?
        + Other effects the function has when it is called

## Writing Documentation
- In a previous reading/lab we encountered the following function:
```py
def distance(p1, p2):
      diffx = p2.getX() - p1.getX()
      diffy = p2.getY() - p1.getY()
      return math.sqrt(diffx**2 + diffy**2)
```
- Let's write some documentation for it!

## Writing Documentation
```py
def distance(p1, p2):
    diffx = p2.getX() - p1.getX()
    diffy = p2.getY() - p1.getY()
    return math.sqrt(diffx**2 + diffy**2)
```

1. **Purpose:** Finds the distance between two points
2. **Parameters:**
    - `p1`, a `Point`
    - `p2`, a `Point`
3. **Returns:**
    - a `float`

# Docstrings

## Docstrings
- A **docstring** is the primary way of writing documentation in Python
- The format of the documentation allows for generating a summary of your code

---

- 
 There are many standards for how to format docstrings
- 
 We will use **Google's** standard in this class

## Single-Line Docstrings
- For simple functions, a **single line docstring** is sufficient that simply states the purpose of the function
- 
 Docstrings are the **first thing** that follows a function declaration
- 
 We usually use **three quotes** instead of one:
    ```py
    def distance(p1, p2):
        """Returns the distance between points p1 and p2"""
        diffx = p2.getX() - p1.getX()
        diffy = p2.getY() - p1.getY()
        return math.sqrt(diffx**2 + diffy**2)
    ```

## Multi-Line Docstrings
- For complicated functions, more documentation is usually needed to clarify how it works
- We would use a **multi line docstring** in this case

## Multi-Line Docstrings
```py
def draw_cloud(win, x, y):
    cm = Circle(Point(x, y), 50)
    cm.setFill("white")
    cm.setOutline("white")
    cm.draw(win)
    cl = Circle(Point(x-25, y), 40)
    cl.setFill("white")
    cl.setOutline("white")
    cl.draw(win)
    cr = Circle(Point(x+25, y), 40)
    cr.setFill("white")
    cr.setOutline("white")
    cr.draw(win)
```

## Multi-Line Docstrings
```py
def draw_cloud(win, x, y):
    """Draws a cloud on the window centered at (x, y)

Parameters:
        win: a GraphWin object
        x:   a float
        y:   a float

Returns:
        Nothing; called for the side effect

Preconditions:
        win must be open

Postconditions:
        draws three white circles (x, y) on win
         * one with radius 50 centered at (x, y)
         * two with radius 40 offset by 25 units to the
           left/right
    """
    cm = Circle(Point(x, y), 50)
    cm.setFill("white")
    cm.setOutline("white")
    cm.draw(win)
    cl = Circle(Point(x-25, y), 40)
    cl.setFill("white")
    cl.setOutline("white")
    cl.draw(win)
    cr = Circle(Point(x+25, y), 40)
    cr.setFill("white")
    cr.setOutline("white")
    cr.draw(win)
```

## Another Example
- Let's write documentation for the `bound_between` function from the previous lab

```py
def bound_between(val, lower, upper):
    return min(max(val, lower), upper)
```