A better way to do code documentation

Photo by Iñaki del Olmo on Unsplash

There are several common ways people do code documentation, some people may use word documents, some others may add tones of remarks or commands at the beginning of the code, and lastly to using third-party tools. However most of the time we forgot about who are our target audience, and most of the time we are doing it due to some prior action. Most likely we doing documentation is because other programmers able to continue the project even some of us are absent. So let’s have a look at one of the document examples below:

The code itself is looking perfectly fine, there does not have any syntax error in the code. However, the logic explained in the remark part is not aligned with the code itself. This is commonly found in code, and most of the time it is due to programmers rarely maintaining texts that are not affecting the program. Most of the time these remarks will remain as it is till the day the whole file be removed. So how should we document it in a way, where the programmer had to modify it when code is updating.

One of the better options will be developers are mandatory to write a unit test to cover and explain the function. Which will be the example below:

The benefits of doing documentation in this way can ensure the written test will be easy to align with the description text stated above. It also will easily sport out any misalignment between the actual result and the title above, forcing the developer to update the description when any changes in the code. At the same time, it increases the reliability of the description text and validates the code constantly before any releases.

The is another option to reduce the dependency on remarks, that is using type restriction on the code and applying a better naming convention on the function. For example, if you are a javascript developer, you should master the latest ES coding syntax and apply typescript in your program.

Like the example above it give a clear message. What is the function about, what parameter it accepts, and what value will be returning, when you consume the function.

In the end, I personally think that if we practice clean code, master the language syntax, and write unit tests you are already doing the documentation for internal use. But there always has an exception, if your library will be used in the public or larger groups. A documentation file stills needed to speed up the learning process but the function that needs to document should be the public function only.




A Chinese Malaysian programmer, who try to practice writing :)

Love podcasts or audiobooks? Learn on the go with our new app.

Recommended from Medium

JAMstack best practices: Adding a serverless back-end to Angular

Build a Stock Chart Using AnyChart JavaScript Library

React applications in ServiceNow Service Portal

7 Different Ways To Implement Micro-Frontends With React

React Native Meetup Bangalore — August 2017

Getting Started with React and MapBox GL JS

LWC Wire and Imperative

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Jit Chan

Jit Chan

A Chinese Malaysian programmer, who try to practice writing :)

More from Medium

My Journey to DLithe Bootcamp

How to Hire Front-End Developers: Steps You Should Follow

How To: Explain Coding Projects To A Team Of Non-Coders

GitHub Copilot in flight