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

2# Formatting

4> Code layout, indentation, and parenthesis placement.

6## Indentation

8Use **2 spaces** for indentation. Never tabs.

10```scheme

11(define (factorial n)

12 (if (zero? n)

13 1

14 (* n (factorial (- n 1)))))

15```

17## Parentheses

19**Never put closing parens on their own line.** Stack them at the end.

21```scheme

22;; Good

23(define (greet name)

24 (string-append "Hello, " name "!"))

26;; Bad

27(define (greet name)

28 (string-append "Hello, " name "!")

29)

30```

32## Line Length

34Keep lines under **80 characters**. Break long expressions sensibly.

36```scheme

37;; Too long

38(define result (some-function arg1 arg2 arg3 arg4 arg5 arg6 arg7))

40;; Better

41(define result

42 (some-function arg1 arg2 arg3

43 arg4 arg5 arg6

44 arg7))

45```

47## Function Definitions

49Short functions on one line:

51```scheme

52(define (square x) (* x x))

53(define (add1 x) (+ x 1))

54```

56Longer functions with body indented:

58```scheme

59(define (process-items items)

60 (filter valid?

61 (map transform items)))

62```

64## Let Bindings

66Align binding values when it improves readability:

68```scheme

69(let ((name (get-name user))

70 (age (get-age user))

71 (active (user-active? user)))

72 (format "~a (~a)~a" name age

73 (if active "" " [inactive]")))

74```

76Or use simple indentation:

78```scheme

79(let ((name (get-name user))

80 (age (get-age user)))

81 (process name age))

82```

84## Cond and Case

86Align clauses with the opening paren:

88```scheme

89(cond

90 ((null? lst) 'empty)

91 ((pair? lst) 'list)

92 (else 'other))

94(case type

95 ((a b c) (handle-abc))

96 ((x y z) (handle-xyz))

97 (else (handle-default)))

98```

100## Lambda

101

102Short lambdas inline:

103

104```scheme

105(map (lambda (x) (* x 2)) items)

106(filter (lambda (x) (> x 0)) numbers)

107```

108

109Multi-line lambdas indented:

110

111```scheme

112(map (lambda (item)

113 (let ((name (item-name item)))

114 (string-upcase name)))

115 items)

116```

117

118## Match

119

120Align patterns with the opening:

121

122```scheme

123(match value

124 ('() "empty")

125 ((x) (format "single: ~a" x))

126 ((x . rest) (format "head: ~a, tail: ~a" x rest)))

127```

128

129## Blank Lines

130

131One blank line between top-level definitions:

132

133```scheme

134(define (foo x)

135 ...)

136

137(define (bar y)

138 ...)

139```

140

141Group related definitions together, separate groups with blank lines:

142

143```scheme

144;; Constructors

145(define (make-point x y) ...)

146(define (make-rect x y w h) ...)

147

148;; Predicates

149(define (point? x) ...)

150(define (rect? x) ...)

151```

152

153## Comments

154

155Align comments with code they describe. Add a blank line before a comment that introduces a new section:

156

157```scheme

158(define (complex-operation x)

159 ;; First, validate input

160 (validate x)

161

162 ;; Then process

163 (process x))

164```

165

166End-of-line comments after two spaces:

167

168```scheme

169(define pi 3.14159) ; Approximation

170```

171

172## Long Argument Lists

173

174When a call doesn't fit on one line, break after the operator:

175

176```scheme

177(create-user

178 name: "Alice"

179 email: "[email protected]"

180 role: 'admin

181 active: #t)

182```

183

184Or align with the first argument:

185

186```scheme

187(send-request client

188 method: 'POST

189 path: "/api/users"

190 body: data)

191```