Python Tutorial: Docstrings

Want to learn more? Take the full course at https://learn.datacamp.com/courses/writing-functions-in-python at your own pace. More than a video, you'll learn hands-on coding & quickly apply skills to your daily work. --- Hi. My name is Shayne Miel. You've probably spent a lot of time using functions that someone else wrote. In this course, you'll learn how to write functions that others can use. Docstrings are a Python best practice that will make your code much easier to use, read, and maintain. Look at this split_and_stack() function. If you wanted to understand what the function does, what the arguments are supposed to be, and what it returns, you would have to spend some time deciphering the code. With a docstring though, it is much easier to tell what the expected inputs and outputs should be, as well as what the function does. This makes it easier for you and other engineers to use your code in the future. A docstring is a string written as the first line of a function. Because docstrings usually span multiple lines, they are enclosed in triple quotes, Python's way of writing multi-line strings. Every docstring has some (although usually not all) of these five key pieces of information: what the function does, what the arguments are, what the return value or values should be, info about any errors raised, and anything else you'd like to say about the function. Consistent style makes a project easier to read, and the Python community has evolved several standards for how to format your docstrings. Google-style and Numpydoc are the most popular formats, so we'll focus on those. In Google style, the docstring starts with a concise description of what the function does. This should be in an imperative language. For instance: "Split the data frame and stack the columns" instead of "This function will split the data frame and stack the columns". Next comes the "Args" section where you list each argument name, followed by its expected type in parentheses, and