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

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

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:

https://medium.freecodecamp.org/code-comments-the-good-the-bad-and-the-ugly-be9cc65fbf83medium.freecodecamp.org