Comments¶

Most comments in Idio are line comments which start with a semi-colon, ;, and run to the end of the line:

;; say something important

echo "Hello World"   ; this is it!

There’s no functional difference between the number of semi-colons forming the start of a line comment (the first one marks the start!) but, historically, some code editors have used the number to distinguish the indentation level of the comment:

one semi-colon for comments on the same line as a piece of code to be aligned towards the right margin
two semi-colons for comments to be aligned at the same indentation level as the adjacent code
three (or more) semi-colons to comments to be aligned at the left margin

Block comments¶

Putting semi-colons at the start of each line of a comment is okay for a small-ish number of lines but at some point you’ll want to comment out entire blocks of code (or commentary!). This is where block comments come into their own.

Block comments are delimited by #* through to a (matching) *# and ignore line comments. We can comment out the whole body of the file with:

#*

Ignore the lot!

;; say something important

echo "Hello World"   ; this is it!

*#

Block comments can be nested. Notice, here, how the inner block comment includes the line comment but that the semi-colon doesn’t break the nesting, it is just ignored:

#*

Ignore the lot!

;; say something important

echo "Hello World"   #* ; nested block comment *#

*#

If, for some reason, your existing line comment includes the end block comment delimiter, you can escape it with a backslash:

#*

Ignore the lot!

;; say something important

echo "Hello World"   ; is this it? \*#  phew!

*#

Semi-Literate Comments¶

With a nod toward’s Knuth’s Literate Programming, Idio support semi-literate comments which are #| (up to a newline) through to a (matching) |#. The text after the #| would describe some mechanism for processing the body of the semi-literate comment. This idea has gone no further so please don’t use them.

Semi-literate comments behave similarly to block comments, including nesting and both types are mutually aware. The idea, here, is that you can (block) comment out a semi-literate comment and, correspondingly, include a block comment in a semi-literate comment.

Expression Comments¶

A final, rarely-used form of comment is the expression comment. Here, #; comments out the next expression which might be more or less than you think.

It is usually used to comment out a multiline expression:

before thing
#;(do
     some
     thing)
after thing

Last built at 2024-11-21T07:11:43Z+0000 from 77077af (dev) for Idio 0.3