-
Notifications
You must be signed in to change notification settings - Fork 1
/
glue_design.html
123 lines (116 loc) · 7.36 KB
/
glue_design.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
<!DOCTYPE html>
<html>
<head>
<meta charset='utf-8'>
<title> design of glue - how and why </title>
<script src="jquery.js"></script>
<script src="jquery-cookie.js"></script>
<script src="jquery-tablesorter.js"></script>
<script src="strftime.js"></script>
<script src="mustache.js"></script>
<script src="config.js"></script>
<script src="main.js"></script>
<link rel="stylesheet" type="text/css" href="templates/reset.css" />
<link rel="stylesheet" type="text/css" href="templates/hack.css" />
<link rel="stylesheet" type="text/css" id="lights_css" />
<script>
var DOCNAME = 'glue_design'
var PROJECT = 'glue'
//set the lights before rendering starts
set_lights()
</script>
</head>
<body>
<header>
<div class="container">
<div class="btn-container btn-lights-container">
<a href="#" class="btn btn-lights" id="lights">lights</a>
</div>
<div class="btn-container btn-home-container">
<a href="/" class="btn btn-home">luapower</a>
</div>
<table id="header_table">
<tr>
<td style="vertical-align: middle;" width="100%">
<h1> design of glue </h1>
<h2> how and why </h2>
</td>
<td style="vertical-align: middle;" align="right" style="height: 150px">
<table><tr><td>
<div class="doc" id="package_info_container">
<div id="package_info"> </div>
<div id="commit_log"> </div>
</div>
<a href="https://github.com/luapower/glue" class="btn btn-rightside btn-github"><span class="icon"></span>View on GitHub</a>
</td></tr><tr><td>
<a href="https://github.com/luapower/glue/tarball/master" class="btn btn-rightside">Download as .tar.gz</a>
</td></tr><tr><td>
<a href="https://github.com/luapower/glue/zipball/master" class="btn btn-rightside">Download as .zip</a>
</td></tr></table>
</td>
</tr>
</table>
<div class="btn-container btn-discuss-container">
<a href="https://github.com/luapower/glue/issues/new" target="_blank"
class="btn btn-rightside btn-discuss"><span class="icon"></span>Discuss</a>
</div>
</div>
</header>
<div class="bg-container">
<div class="bg-center-container">
<div class="bg bg-glue" style="background-image: url('bg/glue.png');"></div>
</div>
</div>
<div class="under-header">
<div class="container">
<div id="toc_container" class="toc_container doc"></div>
<button id=tab1_button class="tab_button hidden">Documentation</button>
<button id=tab2_button class="tab_button hidden">Package Info</button>
<div id="tabs_cointainer">
<div id="tab1_container">
<section class="doc">
<span id="module_info"></span>
<h2 id="scope">Scope</h2>
<p>A small, highly useful bag of tricks.</p>
<p>This API must be <em>compact, not complete</em>. This is the one API that should fit comfortably in someone's head. Adding rarely used or too specialized functions is thus harmful.</p>
<p><em>Every</em> function should come with compelling real-world examples in its defense. In fact, the library should only be permitted to grow from real-world examples which should be used to document and justify the inclusions.</p>
<h2 id="naming">Naming</h2>
<p>The idea is to find the most popular, familiar and <em>short</em> names for <em>each and every</em> function (no underscores and no capitals). Python gets this right, so does UNIX. A function with an unheard of name or alien semantics will be avoided. People rather recall known names/semantics rather than learn unfamiliar new names/semantics.</p>
<p>For non-obvious O(n) operations, use verbs to emphasize the process rather than the result, eg. <code>scan(t,e)</code> not <code>indexof(e,t)</code>, <code>count(t)</code> not <code>size(t)</code>.</p>
<h2 id="semantics">Semantics</h2>
<p>They follow the general <a href="api-design.html">api-design</a> rules.</p>
<h3 id="objects-vs-glue">Objects vs glue</h3>
<p>Don't provide data structures like list and set in a glue library, or a way to do OOP. Instead just provide the mechanisms as functions working on bare tables. Don't do both either: if your list type gets widely adopted, your programs will now be a mixture of bare tables (this is inevitable) and lists so now you have to decide which of your lists has a <code>sort()</code> method and which need to be wrapped first. A global <code>glue.sort(t)</code> spares you the trouble.</p>
<h3 id="write-in-lua">Write in Lua</h3>
<p>String lambdas, callable strings, list comprehensions are all fun, but even the simplest DSLs have a learning curve, complex semantics and performance corner cases, and become a barrier to reading other people's code. I remember loathing having to use Lua's unfamiliar regex language with non-linear performance to do all of my string chores.</p>
<p>Adding DSLs make reading code frustrating. Why not give them <em>an identity of their own</em> and ship them as individual libraries and see if they can claim the required learning time from programmers by themselves.</p>
<h3 id="sugar">Sugar</h3>
<p>Don't add shortcut functions except when calling the shortcut function makes the code more readable than the equivalent Lua code.</p>
<p>If something is an [tricks idiom], don't add a function for it, use it directly. Chances are its syntax will be more popular than its name. Eg. it's harder to recall and trust semantic equivalence of <code>isnan(x)</code> to the odd looking but mnemonic idiom <code>x ~= x</code>. That doesn't mean <code>a < b and a or b</code> is an idiom for <code>min</code> though, <code>min</code> itself is the idiom as we know it from math (wish there were a <code>sign()</code> function too).</p>
<p>Functional programming sugars like <code>compose</code> and <code>bind</code> makes code harder to read because brains are slow to switch between abstraction levels unless it's a self-contained DSL with radically different syntax and semantics than the surrounding code. Eg. it's relatively easy to read a Lua string pattern or an embedded SQL string more than it is reading expressions involving <code>bind</code> and <code>compose</code> which force you to simulate the equivalent Lua syntax in your head.</p>
<p>Sugars like "message %s" % arg are the good ones: % is odd enough to put after a string constant that it has an idiomatic quality, and its semantics is self-evident by reading the format string literal, even for someone who never heard of python's <code>%</code> operator. Also, a prefix notation is generally more readable than a function call.</p>
<h2 id="implementation">Implementation</h2>
<p>Keep the code readable (didactically when possible) and compact. Code changes that compromise these qualities for optimization should come with a benchmark to justify them.</p>
<p>Document the limits of the algorithms involved with respect to input, like when does it have non-linear performance and how it is stack bound. Performance characteristics are not an implementation detail.</p>
</section>
</div>
<div id="tab2_container" class="doc"></div>
</div>
</div>
<div class="container">
<footer>
<div id="disqus_thread"></div>
<div class="faint">[email protected] | <a href="http://unlicense.org/">public domain</a></div>
</footer>
</div>
</div>
<script type="text/x-mustache" id=info_tab_template>
<h3>Modules</h3>
<ul>
{{#module_array}}
<li>{{name}}</li>
{{/module_array}}
</ul>
</script>
</body>
</html>