Colors
Good to know: Storybook canvas embeds don't just work great for live components, you can also embed things like icons, or your color palette or typography tokens just as easily!
Do You Know What A Docstring Is?
Image Source: Freepik
Documentation is an essential part of any programming project. It helps other programmers understand what a particular piece of code does, and also documents how to use that code correctly. Documentation is essential in almost every programming project, but it’s especially important for libraries or packages that are intended for public consumption. Even if you’re not writing a library, documenting your code can help other people who use it more easily understand what it does and how to use it correctly. If you’ve ever read the documentation included with Python modules like pandas or numpy, you’ve seen documentation in action. Documentation describes the purpose of a particular piece of code, its inputs and outputs, related resources, and more. There are many different kinds of documentation that are helpful in different situations. In this article we’ll cover four common types: README files, API docs, docstrings and inline comments. All of these can help make your source code more user-friendly as well as easier for others to reuse in their own projects.
README files
A README file is a file that contains essential information about a project, like the project’s name, description, installation instructions, and examples of how to use the project’s code. README files are often the first thing people see when they visit a project’s GitHub page. If your code is being shared publicly, a README file is a must-have. It is the first thing people will look at when they’re trying to use your code in their own projects. It’s your chance to give them all the information they need to get started as quickly as possible. A README file can also be helpful if you’re sharing your code privately, perhaps on an internal code repository. It’s a good place to note any constraints or caveats for the code, as well as instructions for how to install it correctly.
API docs
API docs are documentation that explains how to use your code in detail. They’re often used to describe web APIs and other code intended to be accessed remotely, but they’re also helpful for any code that is meant to be reused by other people. API docs are often generated from comments in the code or from specially formatted comments in the code’s code. You can find examples of how to write API docs for different languages in this wiki. A good API doc begins with a description of the problem the code is designed to solve, followed by a detailed list of inputs and expected outputs. If the code accepts different input types, it’s helpful to include examples of them all. If there are error conditions that might arise, note how the code handles them. Finally, the API doc should end with links to related resources — especially if those resources include information about installing the code. People will only use your code if they can set it up correctly, so make sure they know where to go if they have questions.
Docstrings
The first type of documentation we’ll cover is docstrings — one of the oldest types of documentation. Docstrings are strings of text that appear at the beginning of Python functions and modules and that describe the code they contain. Docstrings have a number of uses, and are especially helpful when you’re sharing code publicly. They can help quickly identify the purpose of a particular function or module, and they can also be used to generate API documentation. To write a docstring, open your Python code editor and start a new line immediately after the function (but before the function’s code). Type the string “docstring” followed by a colon (“:”). You can write as many lines as you need, then finish the docstring with another colon followed by a new line. If the code you’re writing is meant to be reused, the docstring is a good place to provide instructions for how to use the code correctly. You can also use the docstring to indicate the inputs the function expects, any exceptions that might be raised, and any other useful details.
Inline comments
The last type of documentation we’ll cover is inline comments. Inline comments are comments that appear directly in the code itself. They’re useful for quickly noting anything that doesn’t belong in a docstring, like a quick example of how the code works. Inline comments are also helpful for indicating which parts of your code require more detailed documentation. If you’re unsure what information to put in your API doc, inline comments are a good place to start. Inline comments can include any information that might be helpful to a programmer reading your code — even if that information is already included in your API doc or in the code.
Conclusion
Documentation is an essential part of any programming project. It is a great way to help others understand your code, but it can also help you understand your code better. Using some of these common types of documentation can help improve your code and get you more organized. And if you want to take it a step farther, why not try writing a README file? They’re great ways to make your code more accessible to other people and can help you get discovered on GitHub. Whether you’re writing code for public or private use, adding helpful documentation can make your project more user-friendly and make it easier to share with others.
Since code is much more precise than words, here is an implementation of the algorithm:
def trim(docstring):
if not docstring:
return ''
# Convert tabs to spaces (following the normal Python rules)
# and split into a list of lines:
lines = docstring.expandtabs().splitlines()
# Determine minimum indentation (first line doesn't count):
indent = sys.maxint
for line in lines[1:]:
stripped = line.lstrip()
if stripped:
indent = min(indent, len(line) - len(stripped))
# Remove indentation (first line is special):
trimmed = [lines[0].strip()]
if indent < sys.maxint:
for line in lines[1:]:
trimmed.append(line[indent:].rstrip())
# Strip off trailing and leading blank lines:
while trimmed and not trimmed[-1]:
trimmed.pop()
while trimmed and not trimmed[0]:
trimmed.pop(0)
# Return a single string:
return '\n'.join(trimmed)
The docstring in this example contains two newline characters and is therefore 3 lines long. The first and last lines are blank:
def foo():
"""
This is the second line of the docstring.
"""
To illustrate:
>>> print repr(foo.__doc__)
'\n This is the second line of the docstring.\n '
>>> foo.__doc__.splitlines()
['', ' This is the second line of the docstring.', ' ']
>>> trim(foo.__doc__)
'This is the second line of the docstring.'
Once trimmed, these docstrings are equivalent:
def foo():
"""A multi-line
docstring.
"""
def bar():
"""
A multi-line
docstring.
"""
Documentation is an essential part of any programming project. It helps other programmers understand what a particular piece of code does, and also documents how to use that code correctly. Documentation is essential in almost every programming project, but it’s especially important for libraries or packages that are intended for public consumption. Even if you’re not writing a library, documenting your code can help other people who use it more easily understand what it does and how to use it correctly.
If you’ve ever read the documentation included with Python modules like pandas or numpy, you’ve seen documentation in action. Documentation describes the purpose of a particular piece of code, its inputs and outputs, related resources, and more.
There are many different kinds of documentation that are helpful in different situations. In this article we’ll cover four common types:
README files,
API docs,
docstrings and
inline comments.
All of these can help make your source code more user-friendly as well as easier for others to reuse in their own projects.
References and Footnotes
[7] https://readthedocs.org/projects/network-coders/
Copyright
This document has been placed in the public organic visitors.
Acknowledgements
The "Specification" text comes mostly verbatim from the Python Style Guide [5] essay by Guido van Rossum.
This document borrows ideas from the archives of the Python Doc-SIG [6]. Thanks to all members past and present.
View document source. Generated on: 2022-01-25 18:49 UTC. Generated by Docutils from reStructuredText source.
Acknowledgements
Appendix
Any additional information goes here
🔗 Links
Related
Here are some related projects
🛠 Skills
Javascript, HTML, CSS…
Lessons Learned
What did you learn while building this project? What challenges did you face and how did you overcome them?
🚀 About Me
I’m a full stack developer… hands-on 🏆 digital marketing professional with years of experience in SEO, PPC, web design and IT project management. As a Marketing Manager, he has a track record of building channels (SEM, Paid Social, Display,targeted Mobile traffic) from inception stages to profitable scale.
Docutils Project Model
Project components and data flow:
Last updated
