8.9 KiB
Clean Code - Kind/Formality
Table of Contents
Introduction
Kind is a modern and cute programming language featuring formal proofs.
This simple guide describes how we've been writing Kind code and following some principles
of Clean Code. It's inspired by the article of Clean Code JavaScript.
Join us: https://t.me/formality_lang
Variables
Use meaningful and short names. Prefer indentation of symbols like : and =.
Bad
let hero_object = Pair.fst<_,_>(hero_pair)
let hero_index = Pair.snd<_,_>(hero_pair)
let adversary_object = Mons.Map.get(...)
Good
let hero_obj = Pair.fst<_,_>(hero_pair)
let hero_idx = Pair.snd<_,_>(hero_pair)
let adve_obj = Mons.Map.get(...)
Use snake_case over camelCase
Bad
Nat.toString(n: Nat): String
Good
Nat.to_string(n: Nat): String
Use the same vocabulary for the same context
Bad
get_user_info()
get_client_data()
get_customer_record()
Good
get_user()
Use searchable names
We will read more code than we will ever write. It's important that the code we do write is readable and searchable. By not naming variables that end up being meaningful for understanding our program, we hurt our readers. Make your names searchable.
Bad:
set_timeout(86400)
Good:
// Global declaration
seconds_in_a_day: Nat
Nat.mul(Nat.mul(60, 60), 24) //86400
// Local declaration
let seconds_in_a_day = Nat.mul(Nat.mul(60, 60), 24) //86400
set_timeout(seconds_in_a_day)
Don't add unneeded context
Bad:
type Direction {
dir_right,
dir_up,
dir_left,
dir_down
}
...
set_dir(my_obj, Direction.dir_up)
Good:
type Direction {
right,
up,
left,
down
}
...
set_dir(my_obj, Direction.up)
Global Variables
Mons.global_scr_mid: Pos32
Pos32.new(2048u, 2048u, 0u)
Custom Type
// A 2D map of game tiles
Mons.Map: Type
Map(List(Mons.Object))
create_new_map(...): Mons.Map
Functions
Function arguments size
We follow a convention to avoid passing 80 characters length for lines of code. If your function or data type is too long, consider breaking the line.
Bad:
Mons.Game.exec_turn(hero_obj: Mons.Object, adve_obj: Mons.Object, ..., game: Mons.Game) : Mons.Game
Good:
Mons.Game.exec_turn(
hero_obj: Mons.Object,
adve_obj: Mons.Object,
...
game: Mons.Game) : Mons.Game
Functions should do one thing
This is by far the most important rule in software engineering. When functions do more than one thing, they are harder to compose, test, and reason about. When you can isolate a function to just one action, it can be refactored easily and your code will read much cleaner. If you take nothing else away from this guide other than this, you'll be ahead of many developers.
Bad:
type Film {
new(title: String, year: Nat)
}
main: List(Film)
let films = [
Film.new("Fight Club ", 1999),
Film.new("Avatar", 2009),
Film.new("Passengers", 2016),
Film.new("My Neighbor Totoro", 1988)
Film.new("The Silence of the Lambs", 1991)]
let wishlist = List.nil<Film>
for film in films with wishlist:
open film
if Nat.gtn(film.year, 2008) then
List.cons<_>(film, wishlist)
else
wishlist
Good:
type Film {
new(title: String, year: Nat)
}
catalog: List(Film)
[ Film.new("Fight Club ", 1999),
Film.new("Avatar", 2009),
Film.new("Passengers", 2016),
Film.new("My Neighbor Totoro", 1988)
Film.new("The Silence of the Lambs", 1991)]
films_newer_than(year: Nat, films: List(Film)): List(Film)
List.filter<_>(
(f) open f Nat.gtn(f.year, year), // anonymous function, that is, a function without a name
films)
main: List(Film)
let wishlist = films_newer_than(2008, catalog)
wishlist
Avoid negative conditionals
Bad:
player_not_free_to_move(player: Player): Bool
Good:
is_player_free_to_move(player: Player): Bool
Remove dead code
Dead code is just as bad as duplicate code. There's no reason to keep it in your codebase. If it's not being called, get rid of it! It will still be safe in your version history if you still need it.
Use auxiliary functions to get small information about your data
type Mons.Kind{
Mons(ele: Mons.Kind.mons, boss: Bool),
Terrain(ele: Mons.Kind.terrain),
}
type Mons.Kind.mons{
HERO,
MAGE,
POISOLICK,
EMERELDER
}
type Mons.Kind.terrain{
VOID,
FLOOR(lvl: U32, model: U32),
MON_AREA
}
Mons.Kind.is_hero(kind: Mons.Kind): Bool
case kind{
Mons:
case kind.ele{
HERO : true,
MAGE : false,
POISOLICK: false,
EMERELDER: false,
}
Terrain: false
}
Mons.Kind.is_mon_area(adve_kin: Mons.Kind): Bool
case adve_kin{
Mons: false
Terrain:
case adve_kin.ele{
VOID : false
FLOOR : false
MON_AREA: true
}
}
Data Structures
Use getter and setter
Using getters and setters to access data could be better than simply looking for a property. "Why?" you might ask. Well, here's an unorganized list of reasons why:
- When you want to do more beyond getting an object property, you don't have to look up and change every accessor in your codebase.
- Makes adding validation simple when doing a set.
- Encapsulates the internal representation.
- Easy to add logging and error handling when getting and setting.
Good:
Pos32: Type
U32
Pos32.new(x: U32, y: U32, z: U32): Pos32
let pos = 0u
let pos = U32.or(pos, x)
let pos = U32.or(pos, U32.shl(y, 12u))
let pos = U32.or(pos, U32.shl(z, 24u))
pos
Pos32.get_x(pos: Pos32): U32
U32.and(pos, 2047u)
Pos32.set_x(pos: Pos32, x: U32): U32
Pos32.new(x, Pos32.get_y(pos), Pos32.get_z(pos))
Use new for datatype with 1 constructor
Bad:
type Pair <A: Type, B: Type> {
pair(fst: A, snd: B)
}
Good:
type Pair <A: Type, B: Type> {
new(fst: A, snd: B)
}
Organization
Function callers and callees should be close
If a function calls another, keep those functions vertically close in the source file. Ideally, keep the caller right above the callee. We tend to read code from top-to-bottom, like a newspaper. Because of this, make your code read that way.
Identation using 2 spaces
Bad:
Nat.add(n: Nat, m: Nat): Nat
case n { // No espace
zero: m,
succ: Nat.succ(Nat.add(n.pred, m)),
}
Nat.add(n: Nat, m: Nat): Nat
case n { // 4 espaces
zero: m,
succ: Nat.succ(Nat.add(n.pred, m)),
}
Good:
Nat.add(n: Nat, m: Nat): Nat
case n { // 2 espaces
zero: m,
succ: Nat.succ(Nat.add(n.pred, m)),
}
Type notation with reduced spaces
Bad:
Nat.add( n : Nat, m : Nat) : Nat
case n {
zero: m,
succ: Nat.succ(Nat.add(n.pred , m))
}
Good:
Nat.add(n: Nat, m: Nat): Nat
case n {
zero: m,
succ: Nat.succ(Nat.add(n.pred, m))
}
Commas come in the end of the line
Bad:
Game.move(dir: Dir, pos: Pos32): Pos32
case dir {
right: Pos32.add(pos, Pos32.new(1u, 0u, 0u))
, up: Pos32.sub(pos, Pos32.new(0u, 1u, 0u))
, left: Pos32.sub(pos, Pos32.new(1u, 0u, 0u))
, down: Pos32.add(pos, Pos32.new(0u, 1u, 0u))
}
Good:
Game.move(dir: Dir, pos: Pos32): Pos32
case dir {
right: Pos32.add(pos, Pos32.new(1u, 0u, 0u)),
up : Pos32.sub(pos, Pos32.new(0u, 1u, 0u)),
left : Pos32.sub(pos, Pos32.new(1u, 0u, 0u)),
down : Pos32.add(pos, Pos32.new(0u, 1u, 0u))
}
If possible, align constructors using space
Bad:
Game.move(dir: Dir, pos: Pos32): Pos32
case dir {
right: Pos32.add(pos, Pos32.new(1u, 0u, 0u)),
up: Pos32.sub(pos, Pos32.new(0u, 1u, 0u)),
left: Pos32.sub(pos, Pos32.new(1u, 0u, 0u)),
down: Pos32.add(pos, Pos32.new(0u, 1u, 0u))
}
Good:
Game.move(dir: Dir, pos: Pos32): Pos32
case dir {
right: Pos32.add(pos, Pos32.new(1u, 0u, 0u)),
up : Pos32.sub(pos, Pos32.new(0u, 1u, 0u)),
left : Pos32.sub(pos, Pos32.new(1u, 0u, 0u)),
down : Pos32.add(pos, Pos32.new(0u, 1u, 0u))
}
Don't have journal comments
Remember, use version control! There's no need for dead code, commented code, and especially journal comments. Use git log to get history!
Bad:
// 2019-10-10 Add basic Nat functions
// 2020-03-03 Change it to tail recursive
Nat.add(n: Nat, m: Nat): Nat
case n{
zero: m
succ: Nat.add(n.pred, Nat.succ(m))
}
Good:
Nat.add(n: Nat, m: Nat): Nat
case n{
zero: m
succ: Nat.add(n.pred, Nat.succ(m))
}
Considerations
Kind is a new language constantly improving.
Contributions are welcome <3