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.

Comments

[Hendrik Ras]

Change my mind: Code needs no documentation at all. By using clear naming for variables and methods and practice a code style that favors readability you are going to be just fine. Documentation? Write test!

[Lautaro Suarez]

Let me disagree with you Hendrik, i think that tests is a the best suitable place to put all the possible options that our code might go to but is not documentation.
Clear naming variables and method is the way to go but i found as i`ve already metioned documenting a little in case of a big function where we probably don't know the exatcly behaviour of it. We should never have this kind of big method or functions but in case we happened to have them they should be documented, at least the critical parts of it.
Thanks for the comment!

[j4k0xb]

documentation should be used for the "why" and explaining general concepts/behavior, not repeating the code 1:1 as a sentence (i++ // increment i)
also users want a quick overview of what a function does instead of digging through tests...

ironically StringToArray's documentation doesnt provide any extra value:

• how does it convert the string?
• any edge cases?
• description is just the name reworded
• @param, @return is just duplicating the info from typescript

[Lautaro Suarez]

Indeed is probably not the best example but when handling big functions and more specific behaviours you will need a little explanation about what is being expected to receive as a param and what is expected to return besides the types you may o may not add.
If you are already familiarise with the code is different but even though i would recommend documenting a little about we are expecting.
Then i forgot to mention tests where is where you should add all the posible cases that it may have.