GITBOOK-31: change request with no subject merged in GitBook

the-basics/comments.md

@@ -1,13 +1,27 @@
 # Comments
 
-In BuckShotPlusPlus you can tell the compiler, not to read certain part of your code usng comments, if you want to comment a line in bpp, simply use ## for example:
+Comments are an essential tool in any programming language, allowing developers to annotate their code with helpful descriptions, reminders, or explanations. In [BuckshotPlusPlus](https://bpplang.com/), comments are used to provide context or to temporarily disable specific lines or blocks of code without deleting them.
+
+## How it works
+
+### Single-line comments
+
+In [BuckshotPlusPlus](https://bpplang.com/), single-line comments are created using the `##` symbol. Any text following this symbol on the same line will be ignored by the compiler.
+
+Here's an example:
 
 ```
 Test = "cool"
 ## This line will not be read by the compiler
 ```
 
-You can also create multi-line comments using ### to start your multi line comment and ### to close your multi line comment, here is an example:
+In this example, the text "This line will not be read by the compiler" is a comment and will not affect the execution of the code.
+
+### Multi-line comments
+
+For longer comments that span multiple lines, [BuckshotPlusPlus ](https://bpplang.com/)provides a multi-line comment syntax. You can start a multi-line comment with `###` and close it with another `###`.
+
+Here's how you can create a multi-line comment:
 
 ```
 Test = "cool"
@@ -17,3 +31,17 @@ Text will not be
 Read by the compiler
 ###
 ```
+
+In this example, the three lines between the `###` symbols are all part of a multi-line comment and will be ignored by the compiler.
+
+## Use cases
+
+1. **Code Documentation**: Use comments to document your code, explaining the purpose of specific functions, algorithms, or logic.
+2. **Debugging**: Temporarily disable certain lines or blocks of code during debugging without deleting them.
+3. **Collaboration**: Leave notes or reminders for other developers working on the same project.
+
+## Important notes
+
+* Use comments judiciously. While they are helpful, excessive or unnecessary comments can clutter your code.
+* Always ensure that your comments are clear, concise, and relevant to the code they're annotating.
+* Remember that comments are for developers, not the compiler. They won't affect the execution or output of your program.