How to document your code correctly

Sanjay Pandey

Sanjay Pandey

Have you ever got frustrated after understanding a code left by another person?

Well, this happens to me several times while I am understanding someone’s code for further development or injecting to my own project.

So, I came across to a solution i.e. Documentation of your code.

Basics

    1. The code should be written for humans
    2. Commenting is an additional tool that a developer can choose to use or not
    3. Comments are part of the code

Commenting is the solution for many problems or you can say its another development tool

Comments are part of source code and should be treated alike.

A comment is bound tightly to code it relates to. When code changes, the comment needs to be changed or removed as well. Imagine how confusing would be having a hanging comment that is not related to code!

Documentation

Mainly, there are two types of code consumers i.e. Maintainers and external users.

Maintainers are mainly concerned to

  • What the code does
  • How the code does it

External users are interested to know

  • How to use the code

Way to Document your code

function currencyConverter(usdAmount){
  /**
   * Convert USD to INR.
   * @param usdAmount amount in USD
   * @return amount in INR
   */
}
Share on facebook
Facebook
Share on twitter
Twitter
Share on linkedin
LinkedIn

Related Posts

Speech Recognition API

Recently, I got a task to make a Voice Controlled Web Application. Although I was never familiar with such things and their working. So, I