// This is a blog, written with a motive for better usability of code comments.
// Enjoy Reading
Do we need to comment our code 🤔 ?
If you are a developer then you must have a habit of understanding small code and snippets easily.
The practise of distributing small, usually single-line annotations across your code is known as code commenting. These notes are referred to as “comments.”
Some people love ❤️🔥 comments and write them everywhere, some people hate 😵💫 them and don’t write them at all. You should be in the middle.
Comments have no influence on your program, but they are extremely helpful to individuals who are reading your code.
So when it’s NOT OK 🥲 to use Comments ?
😒 Stating the Obvious :
We can easily understand small declarations and states without comments. And when updating we could forget to update the comment, so better not to write that comment.
🧐 Explaining Unclear Code :
We should adopt better naming conventions that help us gain better readability.
⛔️ Commented Out Code :
If the part of the code is being redundant then it shouldn’t be present anymore in the Code files.
💥Noise Comments :
Sometimes you see comments that are nothing but noise. They restate the obvious and provide no new information.
// No, really? Or how about this: /** The day of the month. */
📍Position Markers :
Sometimes programmers like to mark a particular position in a source file.
//////// RETURN HERE AFTER COMPLETING ///////
So when it’s OK 🤩 to use Comments ?
🔖 Legal Information :
Whenever some legal information related to licensing or copyright has to be conveyed.
🖇 Informative Comments:
Sometimes, it is useful to provide basic information about a function in the form of comments.
📍Non Trivial Comments : Sometimes a comment goes beyond just useful information about the implementation and provides the intent behind a decision.
As already introduced before, the developers could have varying experience levels. So when using more complex code constructs such as regular expressions or date parsers. It makes sense to explain the intended behavior.
⛔ ️Warning of Consequences:
Sometimes it is useful to warn other programmers about certain consequences.
🏁 Amplification : A comment may be used to amplify the importance of something that may otherwise seem inconsequential
👌 Use CODA for any documentation purpose
There is nothing quite so helpful and satisfying as a well-described public API. Coda comes with building blocksーlike pages that talk to each other, and buttons that take actionーso anyone can make a doc that can evolve to feel like an app.
Conclusion
A Good code should read like a story, not a puzzle
Commenting involves placing Human Readable Descriptions inside of computer programs detailing what the Code is doing.
Proper use of commenting can make code maintenance much easier, as well as helping make finding bugs faster. Further, commenting is very important when writing functions that other people will use.
Remember, well documented code is as important as correctly working code.
BONUS : You can refer this extension if you want better structuring of your existing comments.
Top comments (0)