build/dev/lib/_pkg/sigil-stdlib/style/naming.md

2# Naming Conventions

4> Standard naming patterns for Sigil code.

6## General Rules

8- Use **lowercase with hyphens**: `calculate-total`, not `calculateTotal` or `calculate_total`

9- Be descriptive but concise: `user-name` not `u-n` or `the-name-of-the-user`

10- Avoid abbreviations unless universally understood: `config` ok, `cfg` discouraged

12## Predicates

14Functions that return a boolean end with `?`.

16```scheme

17(null? '()) ; => #t

18(string? "hello") ; => #t

19(file-exists? path) ; => #t or #f

21;; Define your own

22(define (valid-email? str)

23 (string-contains str "@"))

24```

26## Mutators

28Procedures that modify state end with `!`.

30```scheme

31(set! x 10)

32(vector-set! v 0 value)

33(set-point-x! p 100)

35;; Define your own

36(define (increment-counter! counter)

37 (set-counter-value! counter

38 (+ (counter-value counter) 1)))

39```

41## Conversions

43Procedures that convert between types use `->`.

45```scheme

46(string->number "42") ; => 42

47(number->string 42) ; => "42"

48(list->vector '(1 2 3)) ; => #(1 2 3)

49(symbol->string 'hello) ; => "hello"

51;; Define your own

52(define (point->list p)

53 (list (point-x p) (point-y p)))

54```

56## Constructors

58Use `make-` prefix for explicit constructors with arguments.

60```scheme

61(make-vector 10 0) ; Create vector of 10 zeros

62(make-hash-table) ; Create empty hash table

63(make-channel 5) ; Create buffered channel

64```

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

68```scheme

69(point x: 10 y: 20) ; Not make-point

70(config host: "localhost")

71```

73## Private Helpers

75Internal procedures not meant for export can use `%` prefix.

77```scheme

78(define (%validate-input x)

79 ...)

81(define (public-api x)

82 (when (%validate-input x)

83 ...))

84```

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

88## Constants

90Use descriptive names, optionally UPPER-CASE for emphasis.

92```scheme

93(define DEFAULT-PORT 8080)

94(define MAX-RETRIES 3)

95(define pi 3.14159) ; Lowercase also acceptable

96```

98## Type Names

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

101

102```scheme

103(define-record-type <point> ...)

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

105```

106

107With `define-struct`, plain names are typical:

108

109```scheme

110(define-struct point ...)

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

112```

113

114## Module Names

115

116- Use lowercase with hyphens

117- Organize hierarchically

118- Match directory structure

119

120```scheme

121(sigil core) ; Core module

122(sigil http client) ; HTTP client submodule

123(myapp users api) ; App-specific module

124```

125

126## Parameter Names

127

128Use meaningful parameter names that describe purpose:

129

130```scheme

131;; Good

132(define (send-email recipient subject body) ...)

133(define (connect host port) ...)

134

135;; Avoid

136(define (send-email a b c) ...)

137(define (connect x y) ...)

138```

139

140For well-known single-letter conventions:

141- `n` - count or number

142- `x`, `y`, `z` - coordinates or generic values

143- `i`, `j`, `k` - loop indices

144- `f`, `g` - functions

145- `p` - predicate

146- `s` - string

147- `lst` - list