Comments

Documentation of code is one of the most important tasks of the programmer. Code is very hard to reuse, and often hard to understand, without documentation. We urge the programmer to include at least two kinds of comment:

Inline comments are annotations intended to convey the intent of the programmer for what the code should do. They should be compact, clearly written and judiciously inserted. Include such comments wherever a section of code requires the reader to guess, or think deeply about a nontrivial sequence of statements, or convey assumptions that might not be obvious from the code.
Block comments are longer pieces of documentation. It's useful to include a block comment at the start of a program to describe the program, when it was written, who implemented it and how it may be used.

Morpho supports two syntactic constructs to support comments. The first is introduced by the marker //. After that, any text to the end of the current line is ignored by the Morpho compiler. This style is useful for annotating a statement

var acceleration // in units of m/s^2

The second style of comment is introduced by /* and closed by */. Anything between, including line breaks, is ignored by the compiler. Such comments may therefore span multiple lines. The following comment documents a new class and its usage

/* A new data structure.
   Brief description
   Usage: ... */
class DataStructure { }

Unlike the C language, from which the notation is derived, such comments can be nested within one another

/* A comment /* A nested comment */ */

which facilitates the common exploratory programming practice of "commenting out" a section of code.

While // is most obviously used for inline comments and /* ... */ is oriented to block comments, either style can be used for either purpose depending on the programmer's sense of aesthetics.