I feel like in-code docs are an underexplored design space.
Do you use comments or string literals? Before the function (e.g. JSDoc) or inside it (e.g. Python)?
Which is best? Which is the easiest to write, has the easiest tooling, or the most readable (code/HTML) artifacts?
miniblog.
Related Posts
64
I find it odd that people recommend Docker for sandboxing agentic coding tools. Isn't it easier to just create a separate user account on the machine?
It's an established security boundary, and viewing output is easy (just make the user's home directory world readable).
22
I'm changing method definition syntax in my language:
// old
fun (this: Int) inc(): Int { this + 1 }
// new
method inc(this: Int): Int { this + 1 }
The original syntax was inspired by Go, but the new syntax is more grep-friendly and perhaps more readable. Not sure about the verbosity though. Thoughts?
23
Do you have a favourite way of highlighting text in a CLI error message? Currently I'm using backticks, but I'm wondering what's the most readable.
