Comment on page
Commenting Code
Possibly the most important part of any programming file!
Programming languages allow for lines of text that get ignored by the interpreter or compiler. These are called
comments. Typically there are two types, a single comment and a block comment. Below are some examples:C++, Java, and Javascript
Python
HTML
These three languages use the same comment technique:
// Two 'forward' slashes create a single line comment.
/*
Slash star allow for a block comment
These are more versatile and allow you to put larger, multi-line comments.
It is important to note that a comment or block comment can also be used
to make code "invisible" to the compiler. This helps when testing or
debugging.
*/
// The following line was removed because it breaks things
// System.out.something.that.breaks(someInput);
/* ************************************************************************
* Some programmers even use the asterisk to highlight certain comments. *
* Although most good coders find that annoying and unprofessional *
*********************************************************************** */
Python utilizes the number (#) or pound (no, not hashtag) symbol for a single-line comment. I prefer to call it the octothorpe. Multi-line comments begin and end with three double-quotation marks. Ya, Python is strange quarky.
# This would be a comment line
x = 17 # A nice prime number
"""
This is a multi-line comment in Python. The triple-double, as I just
started calling it in my head. Just now.
Similar to other languages, it is useful for larger comments or commenting
out a large chunk of code.
"""
Even HTML has a comment tag. It is the
<!-- --> tag. Anything between those tags will not be shown on the web page but are visible if the user inspects the HTML file.<!DOCTYPE html>
<html>
<body>
<p>This text is normal.</p>
<p><b>This text is bold. You might say legen<!-- wait for it -->dary.</b></p>
<!-- This text is invisible! -->
</body>
</html>
A more current IDE will allow you to hide or fold the comments so as not to make the code too messy. This is dependent on your dev environment.
Code comments should briefly explain the purpose of the code, not how the code works. A good comment will include a description of how inputs and outputs are related, and a list of any expected side effects. Comments should not explain every line, nor should they try to explain what the code is doing "in layman's terms". What ends up happening is you duplicate your code with English step-by-steps, essentially making your code file twice as long (or longer).
Comments can also be fantastic for learners and alpha versions of a program. You can leave yourself and collaborators a note, comment out some nasty code or test case, or even keep track of changes, like a change log. But those comments should get deleted before a final version is submitted.
Below is a link to a fantastic article on code commenting from FreeCodeCamp:
Last modified 5yr ago