DO comment your TS code

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.

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:

// This is a single-line comment

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

HOWEVER:

// 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:

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:

// 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 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.

/** !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:

class World {
    static has_someone_who_needs_this =
}

Comments

[Thomas Frank]

Your tips on using different formats and keywords for different purposes are very helpful. The use of keywords like TODO and FIXME is also a great Wordle Unlimited way to keep track of tasks and bugs. I'll be adopting these practices in my coding projects.

[Isolde Harlan]

Thank you for such useful information! I was actually searching for this academized.com/write-my-lab-report website online because I want someone to write my lab report and when I was searching for it online, I found your post. I want to know about DO comment your TS code and that is why I took interest in your post.

[Bekmurzin Timur]

Didn't know about IDE picking up on /** */. Thank you!

[Ildar Khabutdinov]

Thank you for such useful information!