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
I do occasionally find myself wanting to use the phrase "you're absolutely right", especially in technical discussions.
I've started avoiding it though. I worry it'd make me sound like I'm just automating my comments.
LLMs have a really unfortunate habit of leaving comments that exactly describe the bug they just fixed. I keep getting code like this:
// Let Alice and Bob log in.
if user_tags is None:
Should lint suppressions be first class syntax or comments?
Adding a proper metadata system (e.g. Clojure or Rust) is a big design space but it's clear which expressions are affected.
Comments are much easier to implement but it's easy for users to get them wrong.
Thoughts?