🖥️
Intro to Computer Science (ICS3U/C)
  • An Introduction to Computer Science
  • Videos & Slides
  • Unit 1: In the Beginning
    • The History of Computers
    • Binary & Logic
      • Bits and Bytes (Binary)
      • Transistors (Changing Bits)
      • Logic Gates
        • Poster
        • Logic.ly
    • The Parts of a Computer
  • Unit 2: Intro to Code
    • How Do We Code?
      • Coding Conventions (Rules)
      • Commenting Code
    • What is HTML?
      • Hello World! (in HTML)
      • HTML Slideshow
    • Hello World!
    • Input / Output
      • The Console
      • Prompt, Alert, Confirm
    • Variables & Data
      • Strings (Text)
      • Numbers (Values)
        • Converting & Rounding
        • The Math Object
          • Random Numbers
      • Booleans
        • Truthiness
      • Arrays
  • Unit 3: Control Flow
    • Conditionals (if this, do that)
      • If...Else
        • Logical Operators
      • Switch / Case
      • Ternary Operators
    • Loops (Repeating Code)
      • For...Loop
      • While & Do/While Loops
    • Debugging
  • Unit 4: Functions
    • Functional Programming
    • User Defined Functions
      • Hoisting and Scope
    • Calling a JS Function
  • TL;DR
    • Programming Basics
    • Slideshows & Demos
    • Javascript Syntax Poster
  • Advanced Topics
    • Recursion
    • Structures & Algorithms
    • Mmm... Pi
  • External Links
    • Typing Club!
    • repl.it
    • Khan Academy
    • Geek Reading
    • ECOO CS Contest
Powered by GitBook
On this page
  1. Unit 2: Intro to Code
  2. How Do We Code?

Commenting Code

Possibly the most important part of any programming file!

PreviousCoding Conventions (Rules)NextWhat is HTML?

Last updated 6 years ago

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:

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

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:

octothorpe
dev environment
LogoPutting comments in code: the good, the bad, and the ugly.freeCodeCamp.org