Skip to main content
College of Engineering
Capstone

Documenting Code

Current standards for documenting software code aim to ensure that the code is understandable, maintainable, and usable by other developers. Here are some widely recognized practices and tools used for documentation. This is not a comprehensive list, and you may find other resources that work better for your project.

Code Comments

  1. Inline Comments: Short explanations within the code to clarify complex logic or specific lines.
  2. Block Comments: Larger sections of comments that describe a block of code or an entire function.
  3. Docstrings: Especially in languages like Python, docstrings are used to describe the purpose of a function, its parameters, and its return value.

Documentation Generators

  1. Javadoc: Used in Java, it generates HTML documentation from Java source code with special comments (/** */).
  2. Doxygen: Supports multiple languages (C, C++, Java, Python, etc.) and generates various output formats.
  3. Sphinx: Primarily used for Python, it converts reStructuredText files into HTML, LaTeX, and other formats.

README Files

  1. README.md: Typically written in Markdown, this file provides an overview of the project, how to set it up, usage instructions, and other relevant information.
  2. CHANGELOG.md: Documents the changes made in each version of the software.

Style Guides and Standards

  1. PEP 8: Python's style guide, which includes recommendations for writing clear and readable code.
  2. Google Style Guides: Available for various languages, including C++, Python, and Java, providing conventions for formatting, commenting, and more.
  3. JSLint/JSHint/ESLint: Tools for enforcing coding standards in JavaScript.

API Documentation

  1. Swagger/OpenAPI: Used for documenting RESTful APIs, providing interactive API documentation.
  2. RAML: RESTful API Modeling Language, another tool for API documentation.

Wikis and Documentation Platforms

  1. GitHub Wiki/GitLab Wiki: Built-in wikis for repositories, useful for more extensive project documentation.
  2. Confluence: A collaboration tool used for creating, sharing, and collaborating on project documentation.
  3. Read the Docs: Hosts documentation, automatically building it from your code repository.

Best Practices

  1. Consistent Commenting: Follow a consistent style for comments and documentation throughout the project.
  2. Clear and Concise Language: Write documentation that is easy to read and understand, avoiding unnecessary jargon.
  3. Regular Updates: Keep documentation up-to-date with the latest changes in the codebase.
  4. Examples and Tutorials: Provide usage examples and tutorials to help new users and developers understand the software.
  5. Automated Documentation: Use tools that automatically generate documentation from the codebase to ensure accuracy and save time.

By adhering to these standards and practices, software teams can create documentation that enhances the usability and maintainability of their code.