An introduction to documenting code

Introduction

In this post, I will try to explain the basics of how to start documenting your code to everyone to understand it or will try ;).

Why is it important?

When embarking on a collaboration or working with a team, especially involving multiple developers, the code might become increasingly confusing, leading everyone to get lost in the complexity of certain functions or algorithms. Explaining everything in a meeting becomes impractical. To address this challenge, various approaches can be employed, which we will explore in this post.

Name convention

The naming convention may appear deceptively simple, yet it can occasionally spark discussions among colleagues regarding the appropriate name for a function. Below, I'll provide you with some essential factors that can guide you in naming your files or functions.

Do's and Don'ts

Do's

• Keep the name short but meaningful

• Include unique identifiers such as project title, etc.

• Be consistent

• Ensure the purpose of the document is easily identifiable

Don'ts

• Common words such as 'letter', 'current', etc.

• Vague titles such as 'array'.

• Symbol characters such as: ?, <>,+, etc.

• Abbreviations that are not commonly understood, or which may frequently change throughout time

I'm particularly highlighting my dislike for abbreviations as they are one of the things I strongly dislike. There's a common belief that keeping names short automatically implies using abbreviations, but I disagree. For instance, I prefer having a file called "arrayToFirstIndex" rather than "arrayToFI" – after all, what does "FI" even stand for? This example serves as a compelling illustration of how brevity is not always the best approach.

Code documentation

This is probably one of the most important things when coding with a group or in a company, documenting your code is just as important as the code.
If we want to maintain the project we are working on and use it longterm we will need to improve our abilities to documenting what we have done.

Block Tags

I have discovered that employing block tags is a highly effective and lucid way to describe what the code accomplishes. It assists in maintaining clean and comprehensible code. While numerous block tags are available, I will outline the ones I frequently use and explain why they are beneficial.

@param: I utilize it specifically to describe the parameter's data type, its name, and the possible values it can accept.

@type: I utilize it to describe the type of it.

@defaultValue: I utilize it to know the default value of a specific variable

@return: I utilize it to know what it would return

@property: This one could be used with objects to describe what each property could do.

Examples:

I'm gonna finish this post with an examples of how to document your code.

As observed, I began by providing a brief description of the function's purpose. Next, I employed the "@param" block tag to specify the parameter's type and expected input. Finally, I detailed the return value, including its type and description.

/**
 * Convert string to an array.
 * @param {string} str - String to convert.
 * @return {Array} An array of the string received.
 */
const StringToArray = (str: string): string[] => {
 let result = str.split(' ')
 return result
}

Conclusion

All in all, I think that this is a really good option to start understanding what it means to document but I would encourage you to do research and I am also I'm gonna leave the documentation of probably one the most used conventions to document your code. https://jsdoc.app/
Cheers.