DEV Community

Cover image for How To Write Good Code Documentation
Bonnie
Bonnie

Posted on

How To Write Good Code Documentation

Code documentation is an important part of software development that often gets overlooked. Writing good code documentation enhances code readability and maintainability.

Also, good documentation facilitates collaboration among developers by ensuring that others (and future you) can understand and work with your code effectively.

In this guide, you will learn:

  • What makes good code documentation
  • Types of code documentation
  • How to use automated code documentation tools

What makes good code documentation

(a). Writing Style

Effective documentation uses clear and simple language. Avoids jargon and complex sentences. Consistency in terminology and formatting also enhances readability.

(b). Structure and Organization

Organize documentation logically, with a clear flow and categorization. Use headings and subheadings to break up the text and make it easier to navigate.

(c). Keeping Documentation Up-to-date

Documentation should always reflect the current state of the code. Regularly review and update the documentation to match code changes. Synchronize documentation updates with version control commits to ensure consistency.

Types of code documentation

There are several types of documentation, which include,

Inline Comments

Inline comments are placed within the code to explain specific lines or blocks of code. They are useful for clarifying complex code logic.

Here are some guidelines for writing good inline comments:

  • Focus on the purpose behind the code rather than restating what the code does, the why not the what.
  • Use short, direct comments to avoid cluttering the code.
  • Ensure comments are directly related to the code they describe and remove outdated comments.

Function and Method Documentation

Documenting functions and methods helps others understand their purpose, usage, and behaviour. Good function and method documentation should include:

  • What the function or method does.
  • Explanation of each parameter, including its type and expected values.
  • An example of how to use the function or method.

Module and Package Documentation

Modules and packages should include documentation that provides an overview of their functionality and structure.

Key elements include:

  • Summary of what the module or package does.
  • Highlights of the main functions and classes provided.
  • Mentioning any dependencies or prerequisites.

Project Documentation

Project-level documentation gives a broad view of the entire project and includes readme files and contributing guides.

Good ****README files should:

  • Briefly describe the project's purpose and scope.
  • Provide clear steps to set up the project.
  • Show examples of how to use the project.

Good CONTRIBUTING guides should:

  • Explain how others can contribute to the project.
  • Outline the coding standards and guidelines contributors should follow.

How to use automated code documentation tools

Several tools and technologies can help streamline the documentation process. One such tool is Mimrr.

Mimrr is an AI tool that you can use to generate documentation for your code and analyze your code for:

  • Bugs
  • Maintainability Issues
  • Performance Issues
  • Security Issues
  • Optimization Issues

Leveraging the power of Mimrr code documentation and analytics will enable you to create, and maintain up-to-date code documentation even when there are regular code changes.

Getting Started With Mimrr

In this section, you will learn how to create a Mimrr account.

Step 1: Go to Mimrr and click the Get Started button.

Image description

Step 2: Then create your Mimrr account using your Google, Microsoft, or GitHub account.

Image description

Step 3: Next, create an organization by adding an organization name and its description. Then click the Create Organization button, as shown below.

Image description

After that, you will be redirected to your Mimrr dashboard to connect the codebase repo that you want to generate documentation for.

Image description

Congratulations! You have successfully created a Mimrr account.

Connecting Your Codebase Repo To Mimrr To Generate Code Documentation

In this section, you will learn how to connect your codebase GitHub repo to Mimrr to generate its documentation and analytics.

Step 1: Go to the dashboard and open the Connect your code to Mimrr drop-down menu. Then click the Connect button.

Image description

Step 2: Then you will be redirected to choose a repository provider. In this case, I will select GitHub as my code provider. Gitlab and Azure Dev Ops are being added.

Image description

Step 3: Next, go to your Mimrr dashboard and open the projects section to add your codebase repository by clicking the Add Project button. Once your project is added, it should look as shown below.

Image description

Step 4: Click on the project to view the generated documentation, as shown below.

Image description

Congratulations! You have successfully generated code documentation for your codebase.

Conclusion

Good code documentation is vital for the success of any software project. By understanding your audience, using the right tools, and following best practices, you can create documentation that is clear, concise, and useful. Start or improve your documentation practices today to reap the benefits of well-documented code.

Top comments (12)

Collapse
 
asmyshlyaev177 profile image
Alex

Tried it on my project.

It offers me to simplify this condition statement:
export const siteUrl = isVercel ? vercelUrl : netifyUrl;
With this :
export const siteUrl = [vercelUrl, netifyUrl][isVercel];

It's can't handle NextJS and TalwindCss for now.

Eslint + conventional code analysis tools are way ahead of this app.

Collapse
 
colematt profile image
Matthew Cole

The second statement isn’t simplified. And you have to create a copy of the two values for vercelUrl and netifyUrl to make the array to be indexed.

Ternary expressions really aren’t bad once you understand the syntax, and they are used in a lot of languages, so you’ll be seeing them again in the future.

Collapse
 
the_greatbonnie profile image
Bonnie

Thanks for the feedback.

Collapse
 
asmyshlyaev177 profile image
Alex

You welcome, I know that this feature is "beta", more like "alpha" tbh. TailwindCss could be considered as anti-pattern, some devs advocate against it.
But Next.js should work out of the box.

Collapse
 
skywarth profile image
skywarth

How would you rate the documentation in my recent project? github.com/skywarth/darkest-PR

Do you think it's good, easy to read?

Collapse
 
the_greatbonnie profile image
Bonnie

Looks great.

Collapse
 
amrtaher1234 profile image
Amr Mohamed

Looks cool but doesn't serve the purpose at least from my own POV.

A typical readme should contain less text and more focus on how to get started instead of jargon, but overall cool!

Collapse
 
skywarth profile image
skywarth

Thanks for the suggestions Amr, appreciated.

Collapse
 
ravavyr profile image
Ravavyr

I'm pretty sure articles like these are called "spam" ?

Collapse
 
the_greatbonnie profile image
Bonnie

Why?

Collapse
 
ravavyr profile image
Ravavyr

2/3 of the post is an advertisement for mimrr....isn't it obvious?

Thread Thread
 
the_greatbonnie profile image
Bonnie

They sponsored the article.