Code Documentation: A Guide for Beginner's??

In this blog we’ll be having a quick look into how to document the code. Before we get into how to properly document code, let's first understand Why is it necessary to document your code?

As we gain more experience in the tech business or software development, we will notice that we spend far more time reading code than developing it. And this may include reading previous versions of your own code, evaluating someone else's documentation in your team, or analyzing code from third-party libraries and their examples.

As a result, we realize that our code should be more readable and maintainable in order to reduce the time it takes to understand it! We'll look at a few tricks and tips to help you make your code more readable and well-documented.

1.?Add comments to your code

The purpose of adding comments to code is to provide an understandable description of what your code is doing.

When commenting a code, keep the following in mind:

a. Do not simply restate what the code is doing.

b. Describe?why. Why is the code doing what it's doing? What's the business assumption or algorithm step?

c. Format your comments for maximum readability. Tab them properly, leave spaces where necessary

d. Try making use of tools/extensions of VS code.

few are?GhostDoc?and?Add JSDoc comments

I personally prefer Add JSDoc for commenting, it is super easy to use.

Check this?article?on MSDN about writing effective comments

2. Write Test Cases

Most of developers write unit tests for their code?to ensure that the code works properly. This helps to detect and protect against bugs in the future.

Essentially test cases provides you an idea of how the code should behave, and we can be confident that this will not cause any problem in production..

For writing test cases, use language/framework-specific tools/libraries. I prefer?Jest?for NodeJS and React. It is fast and secure, and it allows for easy mocking and code coverage

3. Provide a suitable git commit message

Proper git commit messages are beneficial in the following ways:

a. It adds clarity to pull requests (PRs) raised

b. It is the key to effective debugging within a team

c. Makes tracking an implementation easier

There’s a wonderful article about Git commit message

How to write a good commit message

Tip : Add task/issue id in your git commit message, this helps in identifying exact feature which was pushed and it becomes easy to trace it. And git commit messages should be imperative present tense

eg. #task_id commit_message #3201 add google login

4. Maintain proper Readme file

Its an documentation with guidelines on how to use a project. Usually it will have instructions on how to install and run the project. An idle readme should have

a. Project title

b. Project description

c. How to install and run the project

d. Folder structure explanation and challenges

e. Known issues and credits

f. License and versioning

An extension for creating a top-notch Readme file. :?Markdown Preview Enhanced

5. Write a self documented clean code

There's a reason I saved this for last because I wanted to emphasise it as the most important point of all.

There are a few things that a developer should always keep in mind when writing production-level code :

1. Create a logical and manageable folder structure(for React refer?React Project Structure Best Practices for Scalable Application?)
2. Following meaningful naming conventions for files, variables and functions throughout project
3. Avoiding redundant code : Identify which code is getting repeated and try making it generalized by passing variable arguments
4. Commenting : Sometimes devs build a really complex logic and after few months we get to know what we did but hardly able to remember why we did it, so its better if you write some comments whenever it feels necessary.
5. Formatting : One of the way to make your code more readable is to format the code, follow same conventions/intentions throughout project. I use?prettierr extension for formatting.
6. Review your code often :If you code for 8-10 hours per day, try devoting 1-2 hours to reviewing it, where you will look for improvements, optimization, working on complexities (time and space), and documenting the code. This will save you a lot of time in the future, and it will help you grow in a lot better ways. Personally, I prefer the afternoon for this.

Refer this?book?for getting better understanding of Clean Code.

Conclusion

In this section, we looked at how to write a code documentation which will help you make your code more readable and well-documented.

• Add comments to your code
• Write test cases
• Provide a suitable git commit message.
• Maintain proper Readme file
• Write a self documented clean code

Overall, There are many other ways to document your code, use the one which you think is best!