- Write Comments as You Code
- Comments are crucial for understanding code later
- Write comments as you code to capture your thought process
- Aim for a balanced amount of comments, not too few or too many
# Bad (no comments)
for sequence in parsed_sequences:
analyze(sequence)
# Bad (too many comments)
# iterate over the genes in the genome
for sequence in parsed_sequences:
# call the analyze function, passing it each gene as argument
analyze(sequence)
# Good (just enough)
# Analyze the genome
for sequence in parsed_sequences:
analyze(sequence)-
Include Examples (and Lots of Them)
- Examples provide a starting point for experimentation
- Include examples demonstrating key functionality
- Examples can also serve as unit tests
-
Include a Quickstart Guide
- Help users get started with your software quickly
- Use examples, tutorials, videos, or other formats
- Test your quickstart guide to ensure it's effective
-
Include a README File with Basic Information
- The README acts as the homepage for your project
- Include installation, configuration, documentation links, license, testing, and acknowledgments
- Consider using badges to show project status
-
Include a Help Command for Command Line Interfaces
- Document how to use your CLI with a "help" command
- Include usage, subcommands, options/arguments, environment variables, and examples
- Use tools like click (Python) to generate the help command
-
Version Control Your Documentation
- Keep documentation in your version control repository
- Archive rendered documentation for each release
- Provide a changelog to track changes between versions
-
Fully Document Your Application Programming Interface (API)
- Document inputs, outputs, errors, methods, and attributes
- Follow a consistent style guide for API documentation
-
Use Automated Documentation Tools
- Tools like Sphinx, Doxygen, and MkDocs can generate documentation
- Automate API documentation, interactive REST API docs, and more
- Use services like Read the Docs to keep documentation up-to-date
-
Write Error Messages that Provide Solutions or Point to Documentation
- Good error messages state the error, software state, and how to fix it
- Provide guidance in error messages to save users' time
# Bad
print("Error: Translation failed.")
# Good
print("Error: Translation failed because of an invalid codon (\"IQT\") "
"in position 1 in sequence 41. Ensure this is a valid DNA "
"sequence and not a protein sequence.")- Tell People How to Cite Your Software
- Include DOI, BibTeX entry, and written reference in the README
- Use a CITATION file in Citation File Format (CFF)
- Get a DOI for your software from services like Zenodo or JOSS
- Use Consistent Formatting
- Use a consistent style for headers, code blocks, etc.
- Markdown allows for consistent formatting across platforms
### Header 3
#### Header 4
`inline code`
```python
# Code block
print("Hello World!")-
Structure Documentation Well
- Break documentation into logical sections and chapters
- Use tables of contents and cross-references where appropriate
-
Include Visual Aids
- Use diagrams, flowcharts, and screenshots to clarify concepts
- Reference images using relative paths
-
Make Documentation Searchable
- Use proper headings and anchor links
- Consider using a search plugin for websites
-
Keep Documentation Up-to-Date
- Automate documentation updates when code changes
- Encourage contributors to update documentation