@@ -0,0 +1,332 @@
7+Urbit is a principled approach to system design and programming, but it's often not obvious what those principles are. We have many specific terms for the different parts of the project: Arvo is the OS, Hoon is the language, Tlon is the company, Azimuth is the identity system, Ames is the network. But the word most associated with the project is "Urbit", and it's not clear what technically it refers to. It's only a small stretch to say that "Urbit" *is* this set of principles, and that if anybody follows these principles strictly they will create a system that is isomorphic to the Urbit.
9+Some of these are commonly held among many software projects, and some are not. Some are only debatably better than the alternatives, but Urbit exclusively chooses them.
11+We’ll start with a brief description of many principles, then we’ll go into a long-form justification.
17+1) Data is better than code.
19+ Store data in your state, send data over the wire, dispatch based
22+2) Everything should be CQRS.
24+3) (Almost) Everything should be pubsub.
26+4) A subscriber shouldn't affect a publisher.
28+5) Communication between nodes should be communication between
31+ Each message should do one complete thing, and there shouldn't
32+ need to be a sequence of coupled messages.
34+6) Represent your data as closely as possible to the essential structure
37+7) A client's representation of data should be as close as possible to
40+ This blurs the distinction between client and server. It allows
41+ offline-mode, reduces communication to syncing, and decentralizes.
43+8) When mating different paradigms, build one cleanly on top of the
46+ Never try to make them work on some of the same primitives. Never
47+ abuse one to make the other work. For example, ducts in
48+ themselves are very general - if you want to do pubsub, that can
49+ easily be built on top of ducts, but don't pretend that pubsub is
50+ a *part* of the duct system.
52+9) Never misuse an abstraction.
54+ An abstraction provides a certain set of tools; use them and only
57+10) Correctness is more important than performance.
59+11) Be simple and uncompromising in defining what's correct; go crazy
62+ Nock is a great example of this. It contains the character of the
63+ virtual machine, but its asymptotics are bad. Add jets to fix the
66+ Another example is the ACID nature of Arvo. Arvo is a pure
67+ function f(logs) of its event log, so formally Arvo is just a
68+ function run against an event log. A naive implementation has
69+ very bad asymptotics; processing each new event is O(n) in the
70+ number of historical events. Choose the function g(state,log)
71+ such that f(logs ++ log) = g(f(logs),log). Then, as long as you
72+ keep the state in memory, processing each new event is constant in
73+ the number of previous events. This still requires O(n) restart
74+ from disk, but you can also periodically (and non-blockingly)
75+ write a checkpoint of the state to disk, so that restart from disk
76+ is only linear in the number of events since the last checkpoint.
78+12) Correctness is more important than optimality.
80+13) If you don't completely understand your code and the semantics of
81+ all the code it depends on, your code is wrong.
83+14) Deterministic beats heuristic.
85+ Heuristics are evil and should only be used where determinism is
86+ infeasible, such as in cache reclamation.
88+15) Stateless is better than stateful.
90+16) Explicit state is better than implicit state.
92+17) Referential transparency is honesty and stability.
94+ Lack of referential transparency and other forms of
95+ disingenuousness are some of the world's big problems. Only
96+ deviate from referential transparency if absolutely necessary.
98+18) Responsibilities should be clearly separated.
100+ This applies from kernel modules through network citizens.
102+19) Dualities must be faced head-on and analyzed differently at
105+ Statically typed vs. dynamically typed, imperative vs. functional,
106+ code vs. data, and effectful vs. pure can all be a matter of
107+ perspective, and all relevant perspectives must have coherent
110+20) One hundred lines of simplicity is better than twenty lines of
113+ It's not enough for an abstraction to reduce code duplication; it
114+ must actually make the code simpler.
116+21) Prefer mechanical simplicity to mathematical simplicity.
118+ Often mechanical simplicity and mathematical simplicity go
121+22) The Law of Leaky Abstractions is a lie; abstract airtightly.
123+ If your abstractions are leaking, it's not due to some law of the
124+ universe; you just suck at abstracting. Usually, you didn't
125+ specify the abstraction narrowly enough.
127+23) Some cliches are repeated because they are true; others must be
128+ repeated because they are not.
132+<img class="ba" src="https://media.urbit.org/site/posts/essays/pre-03.jpg">
134+### B: Specific Design
136+1) Always ack a dupe; never ack an ack.
138+ It's okay to ack a nack as long as you never nack a nack.
140+2) Never construct or deconstruct a duct.
142+3) Route on wire before sign, never sign before wire.
144+4) Only go from statically typed to dynamically typed if you must.
146+ Once you go into a dynamically typed world, it's hard to go back.
147+ Statically typed is better than dynamically typed, so if something
148+ can be made static, it should be.
150+ Each timeless data structure is a brick in the foundation of
151+ digital civilization.
153+5) Anything with business logic speaks one paradigm; anything that
154+ translates paradigms has no business logic.
156+6) Functionally enforced semantic rules are better security primitives
157+ than memory access restrictions.
159+ A compiler can use type safety as an effective tool to enforce
160+ some classes of security guarantees.
165+1) Code courageously.
167+ If you avoid changing a section of code for fear of awakening the
168+ demons therein, you are living in fear. If you stay in the
169+ comfortable confines of the small section of the code you wrote or
170+ know well, you will never write legendary code. All code was
171+ written by humans and can be mastered by humans.
173+ It's natural to feel fear of code; however, you must act as though
174+ you are able to master and change any part of it. To code
175+ courageously is to walk into any abyss, bring light, and make it
178+2) No time for lazy people.
180+ If there's clearly a right way to do something and a wrong way, do
181+ it the right way. Coding requires incredible discipline. Always
182+ follow conventions, and fire anyone who won't. Anything that can
183+ be solved by discipline is not a real problem.
185+ > "To him who knows to do good and does not do it, to him it is
188+3) When a smart person makes an obviously stupid suggestion, before
189+ responding take a full 60 seconds to envision how you would implement
190+ it and what the effects would be.
195+1) Academia is a succubus.
197+ Academia has a really high ratio of smart people to useful
198+ products. Academia has many genuinely smart and interesting
199+ ideas, but always remember that pursuing them whole-heartedly will
200+ never result in a useful product.
204+ Academia is inefficient, but it's also correct. Those people
205+ wasted a lot of time finding the right answer, but now that
206+ they've done it, you must exploit it. If you don't know the
207+ theory, learn it. No excuse for being "bad at math". Most who
208+ are "bad at math" are simply lazy or fearful. Be strong and of
209+ good courage. If you're truly so bad at math that you cannot
210+ learn it, you should not design systems.
212+3) Not being qualified to solve a problem is no reason not to solve it.
214+ If you don't know how to do it, do it anyway. "We are too young
215+ to realize that certain things are impossible. So, we will do
218+4) The best way to get the right answer is to try it the wrong way.
220+ You cannot design a good system without spending most of your time
221+ in contact with the problem. The bad parts about systems are
222+ rarely obvious in theory, but often in practice.
224+5) Practice tells you that things are good or bad; theory tells you why.
226+ Never use theory to design a good system from scratch; only
227+ practice can tell whether the system is good.
229+6) Everyone must regularly alternate between theory and practice.
231+ There is an eternal wheel of system design. Given a system, use
232+ practice to discover what is bad, missing, or unnecessary. Then,
233+ use theory to fix the bad, add the missing, and remove the
234+ unnecessary. Repeat.
239+1) No code should extend beyond 80 characters, most within 55.
243+3) A text file is a series of lines, each ending with a newline
246+ Corollary: all non-empty text files end with a newline (often
247+ hidden by editors). An empty text file does not end with a
250+4) One block comment is better than interleaved comments on every line.
252+5) Don't name anything you don't have to.
254+ This includes conventional names for variables of particular
255+ types. For example, the conventional name for a variable of type
256+ `path` is `pax`. You should have a good reason for using any
257+ other name for a `path`.
259+ A more recent convention that follows the same principle is to
260+ give the variable the same name as its type.
262+6) If it's the same thing, give it the same name.
264+7) Humans are good at memorizing.
266+8) Abbreviations aren't worth it.
271+1) If it's not deterministic, it isn't real.
273+2) If it's centralized, it isn't real.
275+3) If it's owned by someone else, it isn't yours.
277+4) If it's managed by someone else and you can't change who that is, it
280+5) If it's not yours, it isn't permanent.
282+6) If it's not permanent, it isn't real.
284+7) The way it is isn't always the way it ought to be.
286+ If you can make it the way it ought to be, do so.
288+8) The way it ought to be isn't always the way it is.
290+ Some things can't be made more elegant.
292+ For every ailment under the sun
293+ There is a remedy, or there is none;
294+ If there be one, try to find it;
295+ If there be none, never mind it.
297+9) Timeless software is good software.
299+10) System modules should be designed to be frozen permanently;
300+ conversely, Urbit consists of that system software which admits of a
303+11) The two procedures for achieving timelessness are distillation and
306+ Every temporary or contingent feature in a system module should
307+ eventually either be removed (distillation) or relaxed into
308+ timelessness (generalization). For an example of the result of
309+ both procedures, consider the abstraction of the core in Nock and
312+12) Standardization is better than perfection.
314+ Kelvin versioning stops when we run out of versions, not when
315+ every defect has been rectified.
317+13) That which cannot be Kelvin-versioned should update fluidly and
320+ All incompatible upgrades should provide permanent and automatic
321+ upgrade paths. This is principled permanent backward
324+14) Humans are interactive and temporal; technology is permanent and
327+15) Communities are autonomous.
329+16) Sovereignty necessitates understanding.
331+ If you don't understand a system you're using, you don't control
332+ it. If nobody understands the system, the system is in control.