DEV Community

Code with Dmitrii
Code with Dmitrii

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 - 
 */
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();
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

HOWEVER:

// 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 (7)

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

Collapse
 
isoldeharlan profile image
Isolde Harlan • Edited

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.

Collapse
 
kristtt profile image
Kris

Thanks for info

Collapse
 
ava_aussie_e0710dbefe087f profile image
Ava Aussie

Need help with your computer programming assignments? Our experienced programmers offer top-quality assistance in languages like Python, Java, C++, and more. Get original code, thorough documentation, and timely delivery to achieve excellent grades. Available 24/7 to support your studies. Contact us now for reliable and affordable computer programming assignment help.

Collapse
 
bekmurzintimur profile image
Bekmurzin Timur

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

Collapse
 
ildar_khabutdinov_22990e4 profile image
Ildar Khabutdinov

Thank you for such useful information!

Collapse
 
paribywen profile image
nagoro

Our experienced programmers offer top-quality assistance in languages like Python, Java, C++, and more. yuzde