From e5fbc9490fae2a43416fe6d78e98ab80cf9df6ca Mon Sep 17 00:00:00 2001 From: Aleksandra Nenadic Date: Thu, 27 Nov 2025 09:35:03 +0000 Subject: [PATCH 1/3] Mention autoDostring extension to setup instructions --- learners/installation-instructions.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/learners/installation-instructions.md b/learners/installation-instructions.md index 8aad79225..f8f4569b2 100644 --- a/learners/installation-instructions.md +++ b/learners/installation-instructions.md @@ -344,6 +344,12 @@ You can also change the default command line terminal from the same drop down me ![*Terminal window in VS Code*](fig/vscode-terminal.png){alt="Screenshot of the terminal pane in VS Code highlighting the current terminal type and dropdown menu to open a new terminal with 'Select Default Profile' option highlighted in the menu"} ::: +#### autoDocstring - VS Code Python docstring generator extension (optional) + +You can optionally install [autoDocstring](https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring) - VS Code extension to quickly generate docstrings for Python functions. +It is a very useful extension that can impove and speed up your Python development. + + #### VS Code extensions for Git (optional) You can optionally install the following VS Code extensions (from `View > Extensions` top-level menu) to make your Git experience in VS Code better: From 5ededa5e7e76303f9f27469d8955c2a96e62cc90 Mon Sep 17 00:00:00 2001 From: Aleksandra Nenadic Date: Thu, 27 Nov 2025 09:44:59 +0000 Subject: [PATCH 2/3] Add callout on autoDocstring extension --- episodes/04-code-readability.md | 33 ++++++++++++++++----------------- 1 file changed, 16 insertions(+), 17 deletions(-) diff --git a/episodes/04-code-readability.md b/episodes/04-code-readability.md index f417c3ca9..70c959183 100644 --- a/episodes/04-code-readability.md +++ b/episodes/04-code-readability.md @@ -832,20 +832,13 @@ print("--END--") ## Use docstrings to document functions -Now that we have written some functions, it is time to document them so that we can quickly recall -(and others looking at our code in the future can understand) what the functions do without having to read -the code. +Now that we have written some functions, it is time to document them so that we can quickly recall (and others looking at our code in the future can understand) what the functions do without having to read the code. *Docstrings* are a specific type of documentation that are provided within functions and [Python classes][python-classes]. -A function docstring should explain what that particular code is doing, what parameters the function needs (inputs) -and what form they should take, what the function outputs (you may see words like 'returns' or 'yields' here), -and errors (if any) that might be raised. +A function docstring should explain what that particular code is doing, what parameters the function needs (inputs) and what form they should take, what the function outputs (you may see words like 'returns' or 'yields' here), and errors (if any) that might be raised. -Providing these docstrings helps improve code readability since it makes the function code more transparent and aids -understanding. -Particularly, docstrings that provide information on the input and output of functions makes it easier to reuse them -in other parts of the code, without having to read the full function to understand what needs to be provided and -what will be returned. +Providing these docstrings helps improve code readability since it makes the function code more transparent and aids understanding. +Particularly, docstrings that provide information on the input and output of functions makes it easier to reuse them in other parts of the code, without having to read the full function to understand what needs to be provided and what will be returned. Python docstrings are defined by enclosing the text with 3 double quotes (`"""`). This text is also indented to the same level as the code defined beneath it, which is 4 whitespaces by convention. @@ -879,15 +872,12 @@ def divide(x, y): ``` Some projects may have their own guidelines on how to write docstrings, such as [numpy][numpy-docstring]. -If you are contributing code to a wider project or community, try to follow the guidelines and standards they provide -for code style. +If you are contributing code to a wider project or community, try to follow the guidelines and standards they provide for code style. -As your code grows and becomes more complex, the docstrings can form the content of a reference guide allowing -developers to quickly look up how to use the APIs, functions, and classes defined in your codebase. +As your code grows and becomes more complex, the docstrings can form the content of a reference guide allowing developers to quickly look up how to use the APIs, functions, and classes defined in your codebase. Hence, it is common to find tools that will automatically extract docstrings from your code and generate a website where people can learn about your code without downloading/installing and reading the code files - such as [MkDocs][mkdocs-org]. -Let's write a docstring for the function `read_json_to_dataframe` we introduced in the previous exercise using the -[Google Style Python Docstrings Convention][google-doc-string]. +Let's write a docstring for the function `read_json_to_dataframe` we introduced in the previous exercise using the [Google Style Python Docstrings Convention][google-doc-string]. Remember, questions we want to answer when writing the docstring include: - What the function does? @@ -895,6 +885,15 @@ Remember, questions we want to answer when writing the docstring include: - What output will the function produce? - What exceptions/errors, if any, it can produce? +::: callout + +### autoDocstring: VS Code Python Docstring Generator + +While we can write docstrings manually, [VS Code extension autoDocstring](https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring) can help create the scaffolding for docstrings and speed up the process immensely. +We highly recommend installing it for Python development. + +::: + Our `read_json_to_dataframe` function fully described by a docstring may look like: ```python From d08f2d5c4a896ae05e975d7bbdfea2913220d1d1 Mon Sep 17 00:00:00 2001 From: Aleksandra Nenadic Date: Fri, 5 Dec 2025 10:24:03 +0000 Subject: [PATCH 3/3] Update episodes/04-code-readability.md Co-authored-by: Sarah Stevens --- episodes/04-code-readability.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/episodes/04-code-readability.md b/episodes/04-code-readability.md index 70c959183..e01b16a08 100644 --- a/episodes/04-code-readability.md +++ b/episodes/04-code-readability.md @@ -889,7 +889,7 @@ Remember, questions we want to answer when writing the docstring include: ### autoDocstring: VS Code Python Docstring Generator -While we can write docstrings manually, [VS Code extension autoDocstring](https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring) can help create the scaffolding for docstrings and speed up the process immensely. +While we can write docstrings manually, [VS Code extension autoDocstring](https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring) and other similar tools can help create the scaffolding for docstrings and speed up the process immensely. We highly recommend installing it for Python development. :::