Comments & Best Practices¶

Well-written comments and consistent coding style go hand-in-hand with CrossBasic’s goal of readable, maintainable code. Below are the supported comment syntaxes and some guidelines to create readable, maintainable, and scalable code.

Comment Syntax¶

CrossBasic recognizes two kinds of line comments. Everything from the comment marker to the end of the line is ignored by the compiler.

Marker	Style	Example
`'`	Single-quote	`Dim x As Integer ' ← this is a comment`
`//`	C-style slash	`Print "hello" // ← another comment`

Note: Block (multi-line) comments are not supported. Use repeated line comments or editor-supported folding regions.

Best Practices¶

1. Comment “Why,” Not “What”¶

❌ Don’t write
```
  x = x + 1      ' increment x by one
```
✅ Instead explain purpose or rationale:

x = x + 1      ' move to next item index in the loop

2. Document Public APIs¶

Above every Function, Sub, Module or Class, include a brief summary:

'─── Module: Geometry ───────────────────────────────────────────
' Utilities for 2D shapes: area, perimeter, collision, etc.
Module Geometry

  '─── Compute the area of a rectangle
  Function RectArea(width As Double, height As Double) As Double
    Return width * height
  End Function

End Module

3. Use TODO / FIXME Tags¶

Mark work in progress or known issues so IDEs and code searches can locate them:

' TODO: support negative radius in CircleArea
Function CircleArea(r As Double) As Double
  Return 3.14159 * r ^ 2
End Function

// FIXME: This algorithm is O(n²). Optimize for large n.
Sub ProcessLargeDataset(data As Array)
  …
End Sub

4. Consistent Indentation & Naming¶

Indent 2–4 spaces per block level; avoid mixed tabs/spaces.
PascalCase for modules, classes, functions, subs: Function ComputeTotal()
camelCase for local variables and parameters: Dim itemCount As Integer

5. Keep Routines Short & Focused¶

Aim for ≤ 30 lines per Function/Sub.
If you find deeply nested If/For blocks, consider extracting helper routines.

6. License & File-Header Comments¶

At the top of each script file, include a brief header:

' ================================================================================
' MyScript.xs — Sample CrossBasic script
' Author:    Jane Doe
' License:   MIT (see LICENSE file)
' Created:   2025-05-20
' ================================================================================

7. Harness Debug Logging¶

Use the built-in DEBUG_MODE switch instead of scattering Print statements:

' at program entry
DEBUG_MODE = True

' later in code
If DEBUG_MODE Then
  Print "Entering loop with count=" + Str(loopCount)
End If

Pro Tip: Treat comments as “living documentation”—keep them accurate and up-to-date. Whenever you refactor or extend code, review nearby comments to ensure they still reflect the intent.