git.m455.casa

fa

clone url: git://git.m455.casa/fa

doc/style-guide-programming.md

fa's programming style guide

This document outlines preferred programming styles when contributing to the fa project.

This document is mainly for my friend Will Sinatra who knows I'm not actually as picky as I seem in this guide.

To discuss

• Nothing right now!

Table of Contents

• Naming
  • Kebab case
  • Shortening names
  • Categorizing names
  • Naming locals
  • Naming functions
  • Naming parameters
  • Naming let bindings
• Indentation
  • Text editor configuration
  • let indentation
  • match indentation
• Abbreviations

Naming

This section describes naming conventions related to the shortening of names, locals, functions, and parameters.

This section consists of the following subsections:

• Shortening names
• Naming locals
• Naming functions
• Naming parameters
• Naming let bindings

Kebab case

Prefer kebab case over other cases.

Preferred example(s)

• user-str
• arg-tbl
• some-seq
• local-network

Undesired example(s)

• userStr
• Argtbl
• some_seq
• LocalNetwork

Shortening names

Prefer guessable, three-letter names if you are shortening a name.

Preferred example(s)

• arg-table can be shorted to arg-tbl
• some-sequence can be shorted to arg-seq
• arg-string can be shorted to arg-str
• arg-number can be shorted to arg-num

Undesired example(s)

• arg-table shouldn't be shortened to arg-t
• some-sequence shouldn't be shortened to arg-s
• arg-string shouldn't be shortened to arg-s
• arg-number shouldn't be shortened to arg-n

Categorizing names

Prefer to prefix names with a category if they fall under the same category.

Preferred example(s)

(local cmd-add "add") (local cmd-rm "rm") (local cmd-ls "ls")

Undesired example(s)

(local add-cmd "add") (local rm-cmd "rm") (local ls-cmd "ls")

(Yes, I did this in the original code, and I need to fix it haha!)

Naming locals

Prefer verbose, descriptive local names, unless you can shorten the name according to the Shortening names section.

Preferred example(s)

• number-found
• number-received
• num-found
• num-received

Undesired example(s)

• n-found
• n-received

Naming functions

Prefer verbose, descriptive function names, unless you can shorten the name according to the Shortening names section.

If the function returns true or false, add a ? at the end of the function name.

Preferred example(s)

• nil?
• string?
• user-id->string
• user-id->str
• get-user-id

Undesired example(s)

• stringify-user-id
• user-id-to-string
• s-user-id
• user-id-s
• user-id-to-s

Naming parameters

Prefer verbose, descriptive parameter names, unless you can shorten the name according to the Shortening names section.

Append the parameter type at the end of the name, shortening to a three-letter type, if possible.

Preferred example(s)

(fn greet-user [name-str] (print (.. "Hello, " name-str)))

Undesired example(s)

(fn grt-u [n] (print (.. "Hello, " n)))

Naming let bindings

Prefer verbose, descriptive parameter names, unless you can shorten the name according to the Shortening names section.

Append the parameter type at the end of the name, shortening to a three-letter type, if possible.

Preferred example(s)

(fn greet-two-numbers [num-1 num-2] (let [num-1-str (tostring num-1) num-2-str (tostrign num-2) nums-combined (.. num-1-str num-2-str)] (print (.. "Hello, " nums-combined))))

Undesired example(s)

(fn greet-two-numbers [num-1 num-2] (let [n-1-str (tostring num-1) n-2-str (tostrign num-2) n-combined (.. n-1-str n-2-str)] (print (.. "Hello, " n-combined))))

Indentation

This section describes preferred indentation conventions.

This section consists of the following subsections:

• Text editor configuration
• let indentation
• match indentation

Text editor configuration

Prefer two-spaced indentation, instead of tabs.

let indentation

Indent let bindings so they line up vertically.

Preferred example(s)

(fn greet-two-numbers [num-1 num-2] (let [num-1-str (tostring num-1) num-2-str (tostrign num-2) nums-combined (.. num-1-str num-2-str)] (print (.. "Hello, " nums-combined))))

Undesired example(s)

(fn greet-two-numbers [num-1 num-2] (let [num-1-str (tostring num-1) num-2-str (tostrign num-2) nums-combined (.. num-1-str num-2-str)] (print (.. "Hello, " nums-combined))))

match indentation

Indent match patterns and result functions so they line up vertically.

If the pattern is too long, move the result function one line below the pattern.

Preferred example(s)

``` (match arg-tbl [cmd-add date-str event-str nil] (add date-str event-str)

[cmd-rm date-str nil] (rm date-str))

cmd-help nil cmd-init nil ```

Undesired example(s)

(match arg-tbl [cmd-add date-str event-str nil] (add date-str event-str) [cmd-help nil] (help) [cmd-init nil] (init) [cmd-rm date-str nil] (rm date-str))

Abbreviations

If you start using a new abbreviation, add it to the list below.

tbl = table str = string num = number seq = sequence