sigildocs

Naming Conventions

Standard naming patterns for Sigil code.

General Rules

  • Use lowercase with hyphens: calculate-total, not calculateTotal or calculate_total
  • Be descriptive but concise: user-name not u-n or the-name-of-the-user
  • Avoid abbreviations unless universally understood: config ok, cfg discouraged

Predicates

Functions that return a boolean end with ?.

(null? '())           ; => #t
(string? "hello")     ; => #t
(file-exists? path)   ; => #t or #f

;; Define your own
(define (valid-email? str)
  (string-contains str "@"))

Mutators

Procedures that modify state end with !.

(set! x 10)
(vector-set! v 0 value)
(set-point-x! p 100)

;; Define your own
(define (increment-counter! counter)
  (set-counter-value! counter
    (+ (counter-value counter) 1)))

Conversions

Procedures that convert between types use ->.

(string->number "42")     ; => 42
(number->string 42)       ; => "42"
(list->vector '(1 2 3))   ; => #(1 2 3)
(symbol->string 'hello)   ; => "hello"

;; Define your own
(define (point->list p)
  (list (point-x p) (point-y p)))

Constructors

Use make- prefix for explicit constructors with arguments.

(make-vector 10 0)        ; Create vector of 10 zeros
(make-hash-table)         ; Create empty hash table
(make-channel 5)          ; Create buffered channel

For simple structs, the type name itself is the constructor:

(point x: 10 y: 20)       ; Not make-point
(config host: "localhost")

Private Helpers

Internal procedures not meant for export can use % prefix.

(define (%validate-input x)
  ...)

(define (public-api x)
  (when (%validate-input x)
    ...))

Alternatively, simply don't export them—unexported bindings are module-private.

Constants

Use descriptive names, optionally UPPER-CASE for emphasis.

(define DEFAULT-PORT 8080)
(define MAX-RETRIES 3)
(define pi 3.14159)       ; Lowercase also acceptable

Type Names

Record type names often use angle brackets (R7RS convention):

(define-record-type <point> ...)
(define-record-type <http-response> ...)

With define-struct, plain names are typical:

(define-struct point ...)
(define-struct http-response ...)

Module Names

  • Use lowercase with hyphens
  • Organize hierarchically
  • Match directory structure
(sigil core)              ; Core module
(sigil http client)       ; HTTP client submodule
(myapp users api)         ; App-specific module

Parameter Names

Use meaningful parameter names that describe purpose:

;; Good
(define (send-email recipient subject body) ...)
(define (connect host port) ...)

;; Avoid
(define (send-email a b c) ...)
(define (connect x y) ...)

For well-known single-letter conventions:

  • n - count or number
  • x, y, z - coordinates or generic values
  • i, j, k - loop indices
  • f, g - functions
  • p - predicate
  • s - string
  • lst - list