How do I add comments to my code?

← Getting Started · Ref: Q18

EK9 supports four comment styles:

1. Single-line comments: //

   The most common style. Everything after // until end of line is ignored.
   Example: // This is a comment

2. Documentation comments: opened with <?- and closed with its mirror-image marker

   Used for file headers, JSON metadata, and documentation that tools can extract. Can span multiple lines. IDEs and documentation generators recognise these as extractable documentation. The metadata headers in these QA example files use this style.

3. General block comments: <!- ... -!>

   Used for internal implementation notes NOT intended for documentation extraction. Can span multiple lines.

4. HTML-style block comments: <!-- ... -->

   An alternative to general block comments for developers familiar with HTML syntax. Functionally identical to the exclamation-mark style.

All comment types are processed by the lexer and completely removed before parsing. The parser never sees comment content.

EK9 does NOT support C-style /* */ comments. Use one of the four styles above instead.

Best practices:
- Use // for quick inline notes
- Use documentation comments for type and function documentation
- Use block comments for temporarily disabling code or internal notes

See Q5 for source file structure where comments fit in the file layout.

Example

defines module qa.getting.started.comments

  <?- Documentation comment: describes this function block -?>
  defines function

    <!- General block comment: internal implementation note -!>
    describeComments()
      <- result as String: "comments example"
      // Single-line comment: the most common style
      result: "EK9 has four comment styles"

  <!-- HTML-style block comment: alternative syntax -->
  defines program
    Comments()
      stdout <- Stdout()
      stdout.println(describeComments())

Common mistakes

E50060 — EK9 Stdout has println() not writeLine(). AI trained on other languages generates wrong method names. Triggers E50060 — method not resolved. See ek9 -h Stdout for the full API.

Incorrect:

stdout.writeLine(describeComments())

Correct:

stdout.println(describeComments())

Coming from another language?

Java: // and /** */ Javadoc, Python: # and triple-quote docstrings, Rust: // and /// doc comments, Go: // and godoc conventions. EK9: four distinct comment styles with semantic meaning. Documentation comments are distinct from general comments, enabling tooling to extract only documentation.

Keywords: docstring, comments, javadoc, doc, beginner, documentation, intro, comment, start, inline, block, first, migrate