Update javascript comments guide [english] (#33456)

convert links + lists to markdown
remove redundant information
make it more readable

guide/english/javascript/comments/index.md

@@ -4,13 +4,11 @@ title: Comments
 
 ## Comments
 
-Programmers use comments to add hints, notes, suggestions, or warnings to their source code; they have no effect on the actual output of the code. Comments can be very helpful in explaining the intent of what your code is or should be doing.
+Programmers use comments to add hints, notes, suggestions, or warnings to their source code; they have no effect on the actual output of the code. Comments can be very helpful in explaining the intent of what your code is or should be doing. It is always best practice when starting out to comment more often than not, as it can help those reading your code to understand what exactly your code is intending to do.
 
-It is always best practice when starting out to comment more often than not, as it can help those reading your code to understand what exactly your code is intending to do.
+JavaScript has two main ways of assigning comments in its code.
 
-JavaScript has two ways of assigning comments in its code.
-
-The first way is the `//` comment; all text following `//` on the same line is  considered as a comment. For example:
+The first way is the `//` comment; all text following `//` on the same line is considered as a comment. For example:
 
 ```javascript
 function hello() {
@@ -38,63 +36,37 @@ function hello() {
 }
 hello();
 ```
-The third way is the `/** */` comment, a format popularly known as JSDoc, can be used to clearly describe functions, classes, methods, and variables in your codebase in a detailed way. For example: 
+
+A third way is the `/** */` comment, a format popularly known as JSDoc is a technique similar to the previous style but adds an asterisk on each line commented. They are not necessary for the code to be ignored but can be helpful for readability. For example: 
 
 ```javascript
 /**
  * Adds two numbers together
  * 
- * @param {number} num1 - first parameter
- * @param {number} num2 - second parameter
- * @returns {number}
+ * num1 - first parameter
+ * num2 - second parameter
+ * returns num1 + num2
  */
 function addTwoNumbers(num1, num2) {
   return num1 + num2;
 }
 console.log(addTwoNumbers(10,20)) // will print 30 in the console.
+```
 
-In some cases you may want to prevent code from running for debugging purposes. For example:
+Comments can be very useful for debugging as they can prevent the execution of Javascript code like this:
 ```javascript
 function hello() {
   /*console.log("Hello world!");*/
 }
-hello();
-```
-#### More Information:
-<a href='https://www.digitalocean.com/community/tutorials/how-to-write-comments-in-javascript' target='_blank' rel='nofollow'>How To Write Comments in JavaScript</a>
-<h3>Many IDEs come with a keyboard shortcut to comment out lines. </h3>
-<ol>
-  <li>Highlight text to be commented</li>
-  <li> Use hotkeys to comment out highlighted block
-  <ul>
-    <li>Mac: Push <kbd>Command</kbd> + <kbd>/</kbd></li>
-    <li>Windows: Push <kbd>Control</kbd> + <kbd>/</kbd></li>
-    <li>Most Linux Distros: Push <kbd>Shift</kbd> + <kbd>Alt</kbd> + <kbd>A</kbd></li>
-  </ul>
-  </li>
-  <li>You can also uncomment code by doing the same steps</li>
-</ol>
-
-Comments are also very helpful for code testing as you can prevent a certain code-line/block from running
-
-```javascript
-function hello() {
-  // The statement below is not going to get executed
-  // console.log('hi')
-  }
-hello();
+hello(); //does not log anything
 ```
 
-```
-function hello() {
-  // The statements below are not going to get executed
-  /*
-  console.log('hi');
-  console.log('code-test');
-  */
-}
-hello();
-```
+### Many IDEs come with a keyboard shortcut to comment out lines.
+
+1. Highlight text to be commented
+2. Mac: Push `Command`(Apple Key) + `/`  
+   Windows: Push `Control` + `/`
+- You can also uncomment code by doing the same steps
 
 #### More Information:
-* <a href='https://www.digitalocean.com/community/tutorials/how-to-write-comments-in-javascript' target='_blank' rel='nofollow'>How To Write Comments in JavaScript</a>
+* [How To Write Comments in JavaScript](https://www.digitalocean.com/community/tutorials/how-to-write-comments-in-javascript)