DEV Community

Dmitrii Pavlov
Dmitrii Pavlov

Posted on

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 - 

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

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

// This is a single-line comment

 * This is a multi-line comment
Enter fullscreen mode Exit fullscreen mode


// I can
// do this multi-line

/** or do this single-line */
Enter fullscreen mode Exit fullscreen mode

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

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    
Enter fullscreen mode Exit fullscreen mode

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 */
Enter fullscreen mode Exit fullscreen mode

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 =
Enter fullscreen mode Exit fullscreen mode

Top comments (4)

thomas180399 profile image
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.

isoldeharlan profile image
Isolde Harlan • Edited

Thank you for such useful information! I was actually searching for this 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.

bekmurzintimur profile image
Bekmurzin Timur

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

ildar_khabutdinov_22990e4 profile image
Ildar Khabutdinov

Thank you for such useful information!