How to Write a Code Comments and How to Amend Mistakes You Made When Writing That Code


Many programmers tend to underestimate the importance of comments and documentation. What happens over time is you end up with a pile of code that has no documentation and you don’t know what it really does. This gets even worse if you have multiple people working on the same code base.

At Programiz, we take documentation very seriously for two reasons:

We want to document our code thoroughly so that it is easy for other people in the team to understand what each function or class does.

We want our users to understand how to use our code and classes.

This blog post is going to be a practical guide on how to write a code comment and how to amend mistakes you made when writing that piece of code.

In this post, I am going to show you how to write code comments and also how to amend mistakes you have made when writing that code.

First, let’s talk about comments. Comments are used in code to explain what the block of code is doing, so if you’re reading it later on, or if someone else is reading it, they can understand why the function was written in that way.

For example: We have a function called addTwoNumbers(). This function takes two parameters (a and b) and returns the sum of those two numbers. Now we need to write a comment explaining what this function does. So we write:

// This function adds two numbers together and returns the sum

function addTwoNumbers(a, b) {

return a + b;

}

Now we know what the function does without having to look inside the function itself. But there is also another type of comment in programming which is used for documentation purposes. Documentation comments are very common in JavaScript because they can be used by other developers who will use your code in their projects e.g if you are writing a module for an npm package or an API library for example. These types of comments follow the following syntax:

/*! */

Sometimes, we are writing a program and we do not understand the logic of that piece of code.

Another reason is, when we write a code, we do not understand what each line of code means and it’s function. We just write a line of code without even understanding what it means because when you see it in the internet, you just copy-paste it.

The solution for this problem is to add comments on your code. Comments can help you understand what things mean in programming or what each line of code does. And also, here’s how to amend errors you made when writing that piece of code.

Adding Comments:

Comments are extra bits of text that the compiler ignores. They can be used to:

Describe your code

Explain what’s going on

Make a to-do list

Prevent errors by keeping track of changes you make

Computers aren’t very smart. Even if they’re programmed to do something, they have to be given a lot of information about how that thing is done. If you don’t tell them every step, then they’ll get confused and make mistakes. That’s why you need to spend so much time coding. As a programmer, you’re helping the computer along by telling it exactly what it needs to know in order to execute its commands. Comments are useful for this because they allow you to write in human language, which the computer doesn’t understand but is much easier for people to read and understand than code.

The most common use for comments is describing what your code does. This can be helpful when you’re writing long pieces of code or working with someone else on a project together (or both). For example, let’s say we want to write some code that prints out “Hello World!” but we don’t remember exactly how printf() works yet; maybe it’s been awhile since we’ve used C and all we really remember right

Comments are an important part of programming. They make the program easier to read and understand for humans.

A comment is a programmer-readable explanation or annotation in the source code of a computer program. It is placed in code to clarify its design and purpose, aid future maintenance and implementation, or convey information to users, including other programmers.*

A code comment is any piece of text or character sequence that is ignored by the programming language, but still useful for human readers. Comments are not just a means to understand what a program does, but also to convey why it does it.

In other words, comments should explain the reason of a series of codes rather than what the code does. A programmer reading the code must be able to figure out what the code does without having to read the comments.

For example, if you have written a math method that adds two numbers and returns their sum, do not write comments explaining how addition works. The name of the function itself is self-explanatory (in this case).

Code comments are restricted to single lines and are preceded by // symbol. These type of comments can be used anywhere in the program. There is no limit on how long they can be, and they can span across multiple lines.

/*

C allows you to write comments in your code. Comments help to make your code readable and maintainable. When writing code, it is a good practice to add a comment before each block of code. There are two types of comments in C:

Single-line Comments: A single-line comment begins with two forward slash characters // and ends at the end of the line. The compiler ignores everything from // to the end of the line. This type of comment is useful for comments that occupy only one line:

/* This is a comment */

Header File Comments: A multi-line or block comment begins with /* and ends with */. You can have as many lines as you like in between these two delimiters. For example, consider the following code snippet:

/* This program demonstrates

how comments are written in C */

printf(“Hello World!”);

This program prints Hello World! on screen. This program has a comment before main() function and another before printf() statement.


Leave a Reply

Your email address will not be published. Required fields are marked *