{"assignment":{"_schema_version":2,"course_id":37,"date_created":"2022-06-28T19:00:00+00:00","date_modified":"2026-02-09T19:27:28.764828+00:00","extra_instructor_files":"","extra_starting_files":"","forked_id":null,"forked_version":null,"hidden":false,"id":1003,"instructions":"## Why Document Code?\n\n1. For sharing code,\n2. To organize our current code, and\n3. To make re-reading old code easier\n\nProgrammers write documentation to explain what a function does.\nThis is useful not only for sharing code with other programmers, but also when we come back our code later.\nTo document code, you create comments that are ignored when the code is executed.\nThese comments are for the benefit of humans, not the computer.\n\n## Single-line Comment\n\n```python single-line-comment\n# This line is ignored\na = 0 # The rest of this line is ignored\nb = 0\n```\n\nTo make a single-line comment in Python, you should use the hash symbol (also known as \"pound\" or \"octothorpe\", written as `#`.) Everything after the hash symbol on the same line is completely ignored by your program.\nThese comments are often used to document a single line of code.\nHowever, you must not use single line comments to create docstrings.\n\n## Multi-line Comment\n\n```python example-docstring\ndef my_function(x:int, y:int)->int:\n    \"\"\"\n    The start of this string needed to be\n    indented, otherwise you would have a syntax\n    error!\n    \"\"\"\n```\n\nTo write multi-line comments in Python, you create a triple-quoted string.\nWhen Python evaluates this string, the value is unused, so it is safely ignored by the computer.\nHowever, unlike the single-line comment, that means that the start of a multi-line comment must respect indentation rules as shown here.\nHowever, on the plus side, this triple-quote string counts as the body of the function, so you no longer need the `pass` statement.\nBecause multi-line comments are just string literal values, they must respect the syntax rules of Python, unlike single-line comments.\nSo, you cannot have a multi-line string value on a line with any other code; they must be on their own separate line.\n\n## How Much to Comment?\n\n- **High:** Every line of code\n- **Medium:** Only confusing or large chunks of code\n- **Low:** Only functions\n\nThere are many opinions on when to write comments and no correct answer.\nSome people believe you need to document every single line.\nSome people believe you should only document functions and programs as a whole.\nEventually, you will need to find your own balance.\nFor example, rather than documenting every line, you might only document lines that are particularly confusing, or document a chunk of code.\n\n## Documenting functions\n\n```python full-docstring\ndef fix_capitalization(title: str)->str:\n    '''\n    This function capitalizes the first letter of each\n    word in the title, correctly ignoring prepositions.\n    \n    Args:\n        title (str): A book or movie title\n            that we want to fix.\n    Returns:\n        str: The corrected title\n    '''\n```\n\nMany people agree that, at a minimum, you should document all your functions.\nUse a triple-quoted string as the first line in the definition of the function.\nThen, give a quick description of what the function does.\nTo give complete documentation, you should also explain what the parameters and returned value mean.\nLeave a blank line, and then type `Args:`.\nIndent the next line, and then type the name of the first parameter followed by its type in parentheses.\nOn the same line, write a colon and then describe the parameter.\nIf you need to continue onto the next line, make sure it is indented past the previous line.\nYou should repeat this for all the parameters of your function.\nFinally, write `Returns:` and then on the next line, write the name of the return type followed by a colon and a description of the returned value.\n\n## What Goes Into a Docstring?\n\n1. **Function Purpose**: A brief description of what the function does.\n2. **Parameters**: Describe what the parameters are and what they represent.\n3. **Return Value**: Describe what the return value is and what it represents.\n4. **Examples**: Provide examples of how to use the function and what the expected output is.\n\nDeciding what to write in the Docstring can be tricky.\nThe general guidance is that the reader needs to understand the function's purpose, how to use it, and what to expect from it.\nYou are not obligated to explain _how_ the function works internally, and that is often a distraction.\nInstead, you can focus on the inputs and outputs of the function, and any important details about its behavior.\nExamples can also be helpful in illustrating how to use the function.\n\nSometimes, if you have good parameter and function names, the user of the function can infer how to use the function from the names and types alone.\nBut often, it's helpful to explain them in more detail if there are any surprises.\nIf there are potential ambiguities, then it is worth writing extra text to explain this.\nIf the function is straightforward, then a simple description may be enough.\nThe amount of detail you go into should be proportional to the complexity of the function.\n\nSometimes it is useful to explain the reasoning behind certain decisions or the overall approach taken in the function, or mention \"gotchas\" that users should be aware of.\nFor example, if a function has a particularly complex algorithm, it might be worth explaining the key steps in the docstring.\nOr if the function has any side effects (like printing to the console), those should be mentioned as well.\nHowever, in general, you can just focus on explaining how to use the function, and not how it works.\n\nWhen we learned about defining functions, we previously described the parameters' type and return type as the *signature* of the function. The fact that it has a special name should reinforce that these are especially important pieces of meta-information.\n\n## Missing Docstrings\n\n```python fully-documented-function\nfrom bakery import assert_equal\n\ndef calculate_area(length: int, width: int) -> int:\n    '''\n    This function calculates the area of a rectangle based on its dimensions. \n\n    Args:\n        length (int): The length of the rectangle in feet.\n        width (int): The width of the rectangle in feet.\n    Returns:\n        int: The area in square feet.\n    '''\n    area = length * width\n    return area\n\nassert_equal(calculate_area(5, 6), 30)\nassert_equal(calculate_area(0, 6), 0)\nassert_equal(calculate_area(4, 5), 20)\n```\n\nDocstrings are a little unusual compared to regular comments because they are considered part of the source code.\nOften, beginners will put docstrings in the wrong location: after the function definition, or before.\nHowever, a docstring MUST be the first line of the body of the function or it will not count.\nThe docstring must also be a string literal value; an octothorpe (`#`) will not count.\nHere is an example of a fully documented function in the context of a bigger program.\n\n## Summary\n\n- Documentation is used to explain the purpose of code, especially functions and entire programs.\n- Documentation makes it easier to understand other people's code and your own code.\n- Comments in Python can be written on a single line with the hash sign (`#`) or as a multiline comment with triple-quoted strings (`\"\"\"`). However, triple-quoted strings are still string literal values so they must follow the usual syntax rules and be on their own line.\n- Triple-quoted strings placed directly under the header of a function as the first line of the body will be treated as \"Docstrings\" by Python.\n- Docstrings explain the purpose of functions, the meaning of their parameters, and details about the value returned from the function.\n- If the triple-quoted string is not placed as the first line of the body of the function, it will not be considered a docstring by Python. Instead, it will just be a regular comment.\n\n","ip_ranges":"","name":"2B2) Docstrings Reading","on_change":"","on_eval":"","on_run":"","owner_id":1,"owner_id__email":"acbart@udel.edu","points":0,"public":true,"reviewed":false,"sample_submissions":[],"settings":"{\n  \"header\": \"Docstrings\",\n  \"slides\": \"bakery_functions_docstrings.pdf\",\n  \"youtube\": {\n    \"Bart\": \"jiJjoRE3aUQ\",\n    \"Amy\": \"ofYpDXmKqiA\"\n  },\n  \"video\": {\n    \"Bart\": \"https://blockpy.cis.udel.edu/videos/bakery_functions_docstrings-Bart.mp4\",\n    \"Amy\": \"https://blockpy.cis.udel.edu/videos/bakery_functions_docstrings-Amy.mp4\"\n  },\n  \"summary\": \"In this lesson, you will learn how to document a function.\",\n  \"small_layout\": true\n}","starting_code":"","subordinate":true,"tags":[],"type":"reading","url":"bakery_functions_docstrings_read","version":9},"ip":"216.73.216.157","submission":{"_schema_version":3,"assignment_id":1003,"assignment_version":9,"attempts":0,"code":"","correct":false,"course_id":37,"date_created":"2026-05-20T18:21:36.237420+00:00","date_due":"","date_graded":"","date_locked":"","date_modified":"2026-05-20T18:21:36.237420+00:00","date_started":"","date_submitted":"","endpoint":"","extra_files":"","feedback":"","grading_status":"NotReady","id":2037066,"score":0.0,"submission_status":"Started","time_limit":"","url":"submission_url-745a3dd0-347d-4487-a144-e8ee0cc06120","user_id":2044724,"user_id__email":"","version":0},"success":true}