0% found this document useful (0 votes)
11 views5 pages

3_Code documentation and commenting

Uploaded by

Tanya Verma
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as DOCX, PDF, TXT or read online on Scribd
0% found this document useful (0 votes)
11 views5 pages

3_Code documentation and commenting

Uploaded by

Tanya Verma
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as DOCX, PDF, TXT or read online on Scribd
You are on page 1/ 5

Code documentation and commenting

Code documentation refers to a collection of documents and code comments that


explain how code works and how to use it. Let’s break it down:

Code Comments:
1. Code comments are annotations within the source code itself.
2. They provide context, explanations, or clarifications about specific code
sections.
3. Developers use comments to make the code more understandable for themselves
and others.
4. Common types of code comments include single-line comments (starting
with //) and multi-line comments (starting with /* and ending with */).
5. While comments are essential, they are not the same as comprehensive
documentation.

Code Documentation:
1. Code documentation goes beyond comments and provides a broader
understanding of the entire codebase.
2. It includes:
 External Documentation: Such as user manuals, technical specifications,
design documents, and coding guidelines.
 Internal Documentation: Comments within the code, explaining how
functions, classes, and modules work.
 High-Level Overviews: Descriptions of the overall architecture, purpose, and
functionality of the software.
Types of Code Documentation
Not all code documentation is the same. Collectively, all code
documentation helps contribute to building and maintaining a
comprehensive understanding of the codebase over time. However,
different types of code documentation serve various purposes and
audiences.
 Code comments are inline annotations within the code that explain its
logic, clarify complex sections, or provide context for future developers.
They are the simplest form of documentation and supplement other, more
detailed forms by offering insights into specific code segments or
algorithms.

 Configuration files, such as YAML, JSON, or XML files, are often used
to store a software project's settings, preferences, or other configuration
data. Documentation within these files helps users understand the purpose
and format of each configuration option, facilitating customization and
configuration.

 Documentation Strings (Docstrings) are special code comments


embedded within code to document classes, functions, or modules in a
structured format. They typically describe the entity, its parameters, return
values, and usage examples. Docstrings can be automatically extracted to
generate API documentation or viewed interactively within integrated
development environments (IDEs).

 Class/Module API documentation describes the classes or modules in a


codebase, including their purpose, functionality, attributes, methods, and
any relevant usage examples. It typically provides an overview of the
available classes or modules and how they interact with each other.

 Method/Function API documentation focuses on individual methods or


functions within a class or module. It explains the purpose of each
method, its parameters, return values, and any exceptions it may raise.
This type of documentation helps developers understand how to use
specific functions correctly.

 The README.md file typically resides in the root directory of the


project repository. A README file details the project's purpose,
installation instructions, usage examples, and other relevant information
for developers or users. A README file is often written in Markdown
format—a lightweight markup language with plain-text formatting syntax
—for easy formatting and readability.
Popular Code Documentation Tools
Another highly recommended best practice for better code documentation
is using automated tools to help aid the process.
Here are some excellent tools and frameworks that you can use for
generating code documentation in various formats while saving time and
ensuring that your document remains consistent:
 Sphinx is a documentation tool widely used in the Python community that
supports various markup languages (including reStructuredText and
Markdown) and integrates with popular programming languages like
Python, C/C++, and JavaScript. Sphinx can generate documentation in
multiple formats, including HTML, PDF, and ePub.
 Javadoc is a documentation generation tool for Java projects that uses
special comments (Javadoc comments) embedded within Java code to
generate API documentation in HTML format. Javadoc is commonly used
to document Java classes, interfaces, and methods.

 JSDoc is a documentation generation tool for JavaScript projects that uses


special comments (JSDoc comments) embedded within JavaScript code to
generate API documentation in HTML format. JSDoc supports
documenting functions, classes, variables, and more.

 Doxygen is a documentation generation tool that supports multiple


programming languages, including C++, C, Java, Python, and more. It can
generate documentation from source code comments in various formats,
including HTML, LaTeX, RTF, and PDF. Doxygen is known for its
flexibility and extensive customization options.

 Swagger (now known as OpenAPI) is a framework for designing,


documenting, and testing RESTful APIs. It allows developers to define
API specifications using a JSON or YAML format, which can then be used
to generate interactive API documentation.

 GitBook is a documentation platform that allows you to write and publish


documentation using Markdown or AsciiDoc. It provides a user-friendly
interface for writing documentation, version control integration (with Git),
and publishing documentation as websites or eBooks.
 Various Markdown-based tools and frameworks , such
as MkDocs , VuePress , and Docusaurus , allow you to create
documentation websites from Markdown files. These tools provide themes,
navigation structures, and other features to create professional-looking
documentation sites with minimal effort.

 Various (IDE) plugins or extensions can assist with code documentation.


For example, Visual Studio Code (which also integrates with Codacy )
has extensions like vscode-docs , which provides features for generating
and previewing Markdown documentation.

You might also like