DO comment your TS code
Published: 2024-02-14 04:26:32

Once, while creating a module of code that is complex in its logic, I noticed that I wasn't following any rules of code commenting at all. All comments were scattered with different syntax, distracting from the code and providing no benefits.

```javascript
const me = new CommonFrontend();
class World {}

// Your code isn't as complex as you think
me.has_need_for_writing_articles = 1;

/** Why are you writing this? */
/**
 * TODO - 
 */
me.write_article_for_myself();

// =========
// ! Warning: This article is too simple and no one needs it
//-   Don't write
// =============
if (World.has_someone_who_needs_this) me.go_on();
```

Everyone knows the difference between single-line and multi-line comments:

```javascript
// This is a single-line comment

/**
 * This is a multi-line comment
 */
```

HOWEVER:

```javascript
// I can
// do this multi-line

/** or do this single-line */
```

However, comments in the `/** */` format are recognized as documentation of function, class, or method, while `//` comments are not. So, I started describing entire code blocks with `//` comments (even if they span multiple lines), but variables and functions with `/** */` comments only (preferably exactly in a single line, as they are more common in your code).

Now, when hovering over a function anywhere in the code, I see the comment written above it:

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/wtn4sfzg9ae58013jlf6.png)

Of course, a comment that would describe an entire block or file would hinder understanding the purpose of a function, as it would also be displayed in the popup-description as a documentation of that one exact function.

Here's an example:
```javascript
// Description of some blocks in a file
// Some facts that should be known about classes here
/** 
 * Class description
 * Some
 */
class CorrectCommentedClass {
	/** described */
	constructor() {}

	/** described */
	method() {
		// use such a comment to describe some strings in a functions' body as well    
	}
}
```

Secondly, unused and often buggy code remained behind comments, which we simply forgot about and couldn't find again. To avoid this, use keywords in `/** */` and `//` comments both:

- `!DEPRECATED` - for explicitly outdated code that should be replaced or has already been removed in some places.
- `TODO` - to denote code that needs further implementation.
- `FIXME` - for obvious bugs or potential issues that need to be fixed as soon as possible.
- `*KLUDGE` - description of necessary workarounds and illogical pieces of code, followed by a description of "why?".
These keywords and signs at the beginning are highlighted by the [BetterComments](https://marketplace.visualstudio.com/items?itemName=aaron-bond.better-comments) extension for example or by default (depends on IDE), and you can search for them using these keywords.

And, forgive me, but I really do use this:

- `?WTF` - for parts of the code that I completely don't understand and don't have time to figure out, hoping that one of my colleagues will see this in the code and leave a comment next time.

```javascript
/** !DEPRECATED - why? where is new code? */
/** TODO - what? */
/** *KLUDGE - why? what is it for? */
/** FIXME - describe the bug */
/** ?WTF */
```

And this brings us to the conclusion:

- Write comments for your code. Sometimes I write them before writing the main code - it helps to think through how exactly it should work.
- Every time you need to take a break or have a minute, write comments for the code adjacent to yours.
- Sometimes enter keywords in the search in your IDE, and, if possible, refine `FIXME` and explain to your colleagues `?WTF`.

TU, and write what you think in comments:
```javascript
class World {
	static has_someone_who_needs_this =
}
```