{"assignment":{"_schema_version":2,"course_id":37,"date_created":"2025-08-17T17:31:24.448463+00:00","date_modified":"2025-09-09T21:50:05.782544+00:00","extra_instructor_files":"","extra_starting_files":"","forked_id":null,"forked_version":null,"hidden":false,"id":2465,"instructions":"## Documentation\n\n1. For sharing code,\n2. To organize our current code, and\n3. To make re-reading old code easier\n\nUntil now, documentation has probably seemed like a tedious afterthought to writing programs, done just to appease an autograder.\nIf a function is short and only being used in one place, why bother to write an explanation of what it does?\nYou just wrote it, of course you know what it does.\nPlus, it passes BlockPy's autograder tests, so we know it must be correct!\n\nUnfortunately, this view is short-sighted.\nFirst, it is critical to separate the process of learning how to code from actually writing code.\nAt this early phase of your learning, you are still building your mental model of how code works, and we are giving you short, simple problems that are detached from each other.\nLearning how to integrate and connect together functions into bigger programs is very difficult.\nThere is still pedagogical value in practicing documentation skills, even for small functions, so that you will be ready when we start working on larger projects.\n\nThe reality is that most code is read far more often than it is written - after all, it can only be written once, but it can be read many times.\nDocumentation is one of the key tools we have to make our code more understandable and maintainable, in addition to choosing good variable names, writing tests, and following consistent coding styles.\nWithout documentation, it would be very difficult to share code and work on existing codebases.\n\n## Docstrings\n\n```python example-docstring\n\ndef choose_word(level: int) -> str:\n    \"\"\"\n    Choose a word from a predefined list based on the given level.\n\n    Args:\n        level (int): The level to choose a word for.\n    Returns:\n        str: The chosen word.\n    \"\"\"\n    levels = [\"heat\", \"dogs\", \"jazz\"]\n    return levels[level]\n\n```\n\nThe primary form of documentation in Python is docstrings, where we describe the purpose and behavior of a function or module using a string literal that is the first statement in the function or module.\nThe location and formatting of that string literal is absolutely key, and makes the text recognizable to the Python compiler itself.\nIt's not just convention, it's a fundamental part of how Python works.\n\nThe text of the docstring usually begins with an explanation of the function's purpose, followed by a description of its parameters and return value.\nThe exact structure of that information depends on the conventions used in the codebase and any relevant style guides.\nIn this curriculum, we follow Google's standard.\nThat means we write the word `Args` and the word `Returns` with colons after them, and then write the parameters and return types in a particular way.\nYou should be aware that there are other possible conventions, especially when you encounter other code online.\nHowever, we have found the Google style to be clear and effective for our purposes.\n\n## Reading Documentation\n\n```python printable-wrong\nfrom string import printable\n\n# ...\n\ndef check_if_valid_guess(guess1: str, guess2: list[str]) -> bool:\n    \"\"\" ... \"\"\"\n    return not len(guess1) > 1 and guess1 in printable and guess2 not in guess1\n\n```\n\nExternal documentation can be a valuable resource when working with unfamiliar code or libraries.\nIn this project, something called `printable` gets imported from the `string` module, which is a builtin Python module.\nSearching through the code, it seems to be a variable that gets used in `is_valid_word` and `check_if_valid_guess`.\nWe previously identified that the `is_valid_word` function is not used anywhere, so we can ignore it and focus on `check_if_valid_guess`.\n\n## Searching Effectively\n\n![A screenshot of the Find tool in Thonny, and the search box in Chrome](bakery_projects_documentation_search.png)\n\nKnowing how to search a program is a useful skill.\nProgrammers have developed many tools to make it easier to search effectively.\nMost environments (including your web browser) allow you to search for a specific word or phrase, often by typing `Ctrl+F` (or `Cmd+F` on macOS) to open a search box.\n\nMore sophisticated development environments (like Visual Studio Code or PyCharm) offer advanced search features, such as searching across multiple files or more advanced pattern matching.\nAs you work with larger codebases, these tools become absolutely essential.\nFor now, since we are working in a single file, we can get a lot of mileage out of the basic search functionality.\n\n## Reading a Function\n\n```python check-if-valid-guess\ndef check_if_valid_guess(guess1: str, guess2: list[str]) -> bool:\n    \"\"\"\n    Check if the user's letter guess is valid.\n\n    Args:\n        guess1 (str): The first guess, should be a single letter.\n        guess2 (list[str]): The list of previous guesses.\n\n    Returns:\n        bool: True if the guess is valid, False otherwise.\n    \"\"\"\n    return not len(guess1) > 1 and guess1 in printable and guess2 not in guess1\n```\n\nThe `check_if_valid_guess` function checks if the user's letter guess is valid by ensuring it is a single letter and has not been guessed before.\nThis means the function must take the user's previous guesses (a list of strings) in addition to the current letter being guessed.\nWe'll discuss later about how the parameters' names are poorly chosen and could be more descriptive, but for now, notice how the docstring helps clarify the function's purpose and usage.\nA good heuristic is that if you find yourself having to explain things in a comment, you probably want to rename a variable or function name.\nIn this case, the `guess1` parameter is actually meant to be user's single letter guess.\nThe `guess2` parameter is their list of previously guessed letters.\n\n## Reading External Documentation\n\n![A screenshot of the official Python documentation for the `printable` variable](bakery_projects_documentation_printable.png)\n\nIn this screenshot, we are viewing the official Python documentation for the `printable` variable, at the current time of writing.\nThe formatting is consistent with other variable descriptions in the documentation, showing the name of the module, a period, and then the name of the variable. On the next line is an explanation of the variable and what it contains: a string of all the possible characters you can print in Python.\n\nThere is a grey \"Note:\" box below the description.\nIs this note relevant to our use case?\nYou can't know unless you read it, so make sure you always read the documentation thoroughly.\nBut even after reading it, you might be completely unsure whether it is applicable or not.\nYou might need to do further research on what the note is talking about, or ask a colleague for clarification.\nIn this case, we can clarify that the note is not relevant or helpful, as it explains an important distinction about the term `printable` that experienced users might be confused about, but which has no relevance for our use case.\n\n## Identifying the Conflict\n\n```python printable-correct\nfrom string import ascii_letters\n\n# ...\n\ndef check_if_valid_guess(guess1: str, guess2: list[str]) -> bool:\n    \"\"\" ... \"\"\"\n    return not len(guess1) > 1 and guess1 in ascii_letters and guess2 not in guess1\n```\n\nReading through this documentation, you might have a realization that the documentation of our function and the documentation of this variable are in conflict with its usage.\nThe docstring says that guess should be a single _letter_, but the `printable` variable contains all printable characters, including digits and punctuation.\nAssuming that the docstring is correct, it is likely that we should have used the `ascii_letters` variable instead, which contains only the letters a-z and A-Z.\n\nHow do we know if the documentation is correct, or the code is correct?\nThere's no magical way to tell - you have to think critically about the problem domain and the specific requirements of your application.\nReading over the whole program and applying our other techniques can help clarify the situation.\n\n## Noticing New Things\n\n```python\n@route\ndef play_level(state: State) -> Page:\n    so_far = reveal(state.secret, state.guesses)\n    return Page(\n        state,\n        [\n            Header(\"Level \" + str(state.level)),\n            Div(\"Word: \", so_far),\n            \"Guesses so far: \",\n            BulletedList(state.guesses),\n            \"Guess a letter:\",\n            TextBox(\"guess\"),\n            Button(\"Submit\", \"submit_guess\"),\n        ],\n    )\n```\n\nAs you read through the code, you should be on the lookout for parts that you do not understand.\nPursue clarification on mysteries aggressively.\nFor instance, if you did not understand what the `BulletedList` component does, you should look it up in the documentation.\n\n## Drafter Documentation\n\n![A screenshot of the official Drafter documentation for the Bulleted List component, which takes a list of strings and renders them with bullet points.](bakery_projects_documentation_bulleted_list.png)\n\nThe documentation for the `BulletedList` explains how the component can be used to display a list of items with bullet points.\nIt takes in a list of strings, and renders each string as a bullet point in the list.\nIf you were not sure what that explanation meant, you could try using the component in a simple example to see how it behaves.\nOr you could try looking up the terminology online to gain a better understanding.\nFinally, never be afraid to just go ask for help.\nHowever, try to ask specific questions that will help you get the information you need.\nThe more you are thinking critically and struggling with the material, the more likely you are to learn and remember what you figure out.\n\n## Summary\n\n-   Docstrings can be a valuable source of information about how a function is supposed to be used.\n-   Documentation helps us remember our own thought processes and decisions.\n-   Good documentation can make it easier for others to understand and use our code.\n-   Documentation can also help us identify and fix bugs more easily.\n-   When working with frameworks like Drafter or using built-in Python features, read over documentation from external sources.\n-   When debugging a codebase, critically evaluate the documentation and code to identify discrepancies and areas for improvement.\n","ip_ranges":"","name":"5A3) Documentation","on_change":"","on_eval":"","on_run":"","owner_id":1,"owner_id__email":"acbart@udel.edu","points":1,"public":true,"reviewed":false,"sample_submissions":[],"settings":"{\n  \"small_layout\": true,\n  \"header\": \"Documentation\"\n}","starting_code":"","subordinate":false,"tags":[],"type":"reading","url":"bakery_projects_documentation_read","version":3},"ip":"216.73.216.157","submission":{"_schema_version":3,"assignment_id":2465,"assignment_version":3,"attempts":0,"code":"","correct":false,"course_id":37,"date_created":"2026-05-20T12:38:54.402051+00:00","date_due":"","date_graded":"","date_locked":"","date_modified":"2026-05-20T12:38:54.402051+00:00","date_started":"","date_submitted":"","endpoint":"","extra_files":"","feedback":"","grading_status":"NotReady","id":2036731,"score":0.0,"submission_status":"Started","time_limit":"","url":"submission_url-2d264054-733e-4c40-bfdd-661ca22410a1","user_id":2044658,"user_id__email":"","version":0},"success":true}