forked from ChatScript/ChatScript
-
Notifications
You must be signed in to change notification settings - Fork 1
Expand file tree
/
Copy pathChatScript-Coding-Standards.html
More file actions
173 lines (157 loc) · 9.86 KB
/
Copy pathChatScript-Coding-Standards.html
File metadata and controls
173 lines (157 loc) · 9.86 KB
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
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta http-equiv="Content-Style-Type" content="text/css" />
<meta name="generator" content="pandoc" />
<title></title>
<style type="text/css">code{white-space: pre;}</style>
</head>
<body>
<h1 id="chatscript-coding-standards">ChatScript Coding Standards</h1>
<p>Copyright Bruce Wilcox, gowilcox@gmail.com www.brilligunderstanding.com <br>Revision 10/22/2017 cs7.6</p>
<p>Contents:</p>
<ul>
<li><a href="ChatScript-Coding-Standards.html#indentation-of-rules">Indentation of rules</a></li>
<li><a href="ChatScript-Coding-Standards.html#rule-labels">Rule Labels</a></li>
<li><a href="ChatScript-Coding-Standards.html#give-sample-inputs">Give Sample inputs</a></li>
<li><a href="ChatScript-Coding-Standards.html#easy-to-read-patterns">Easy to read patterns</a></li>
<li><a href="ChatScript-Coding-Standards.html#easy-to-read-rule-output">Easy to read rule output</a></li>
<li><a href="ChatScript-Coding-Standards.html#bundle-related-rules">Bundle related rules</a></li>
<li><a href="ChatScript-Coding-Standards.html#concept-and-function-localization">Concept and Function localization</a></li>
<li><a href="ChatScript-Coding-Standards.html#keyword-casing-and-misspellings">Keyword casing and Misspellings</a></li>
</ul>
<p><em>Rationale</em>:<br> Coding Standards allow you and others to understand your code. They can also allow others who are not programmers to view an abstract of your code, generated by CS’s <code>:abstract</code> ability.</p>
<p>To use <code>:abstract</code>, merely login locally with a new user name (or erase contents of USERS), then type <code>:abstract ~mytopic</code> for a single topic. The abstract will whiz by on screen but is captured in the user log. Just rename that log file and move it somewhere else.</p>
<h2 id="indentation-of-rules">Indentation of rules</h2>
<ul>
<li>Do not indent top level rules.</li>
<li>Indent rejoinders per level.</li>
<li>Leave blank line before top level rule.</li>
</ul>
<p>Examples:</p>
<pre><code>t: How are you
a: (~goodness) glad to hear it.
b: (cool) not so cool.
a: (~badness) sorry to hear it
b: (cool) not so bad. # bad - wrong indentation level
u: (how are you) I am good.
u: (and then) xxx # this is bad - jammed immediately after top level rule
u: (why not) because. # this is bad indentation of top level rule</code></pre>
<p><em>Rationale</em>:<br> On one hand you want to minimize useless space on a page. So top-level rules should not be indented (nor should their sample inputs).</p>
<p>On the other hand you want to easily see the structure of the code, so properly indenting rejoinders makes structure clear. And you want to easily spot where one rule chunk ends and another begins. So separating top level rules and keep rejoinders together is what I do.</p>
<h2 id="rule-labels">Rule Labels</h2>
<ul>
<li>Make meaningful labels using capital letters.</li>
<li>Label all rules that have their own output text.</li>
</ul>
<p>Examples:</p>
<pre><code>t: ASK_FOR_EMAIL () What is your email address?
a: EMAIL_GIVEN (~email_url) Thank you.
a: () ^reuse(EMAIL_GIVEN)
t: B55() What is your email address? # bad- meaningless label</code></pre>
<p><em>Rationale</em>:<br> Using capital letters for rule labels (both at the rule and in places that <code>^reuse</code> the rule) make it easy to see them in a mass of text like a <code>:trace</code>.</p>
<p>If yours is not your own private bot project then every rule that generates output should have such a label, which will appear in an abstract. This allows others to refer to your rule and maybe find it in log files of customers.</p>
<h2 id="give-sample-inputs">Give sample inputs</h2>
<ul>
<li>Give sample inputs for responders and rejoinders.</li>
<li>Give multiple samples for wildly different sentence constructions when you have multiple patterns in a rule.</li>
</ul>
<p>Examples:</p>
<pre><code>t: What year is it?
#! 1993
a: (~year) Great.
#! What is your name
#! Who are you?
?: ([
(‘you [name called])
(who be ‘you)
])
My name is Rose.</code></pre>
<p><em>Rationale</em>:<br> Sample inputs explain your patterns. Instead of having to interpret the pattern, you know immediately what the rule is intending to do.</p>
<p>Sample inputs allow you to use <code>:abstract</code> to give non-programmers an overview of your code. Sample inputs also allow CS to unit-test your code for you using <code>:verify</code>.</p>
<h2 id="easy-to-read-patterns">Easy-to-read patterns</h2>
<ul>
<li>Avoid superfluous parentheses.</li>
<li>For multiple patterns, put each on its own line.</li>
</ul>
<p>Examples:</p>
<pre><code>?: WHAT_BRILLIG_DOES([
(what * “Brillig Understanding” )
([tell talk know] *~2 about “Brillig Understanding”)
])
Brillig Understanding makes natural language systems.
u: BAD_CHOICES ([
(<< Brillig company >> ) # superfluous parens
(~mywords) # superfluous parens
([ word1 word2]) # superfluous parens
])</code></pre>
<p><em>Rationale</em>:<br> Superfluous parens make patterns harder to read, so harder to visually confirm they are correct. They also slow down the CS engine, but not enough to matter.</p>
<p>When you are using multiple patterns in a rule, putting each on its own line allows you (or code reviewers) to comprehend each one separately.</p>
<h2 id="easy-to-read-rule-output">Easy to read rule output</h2>
<p>Indent each sentence and each CS code statement on separate lines.</p>
<p>Examples:</p>
<pre><code>#! Test
u: (test)
$status += 1
$_x = ^compute(1 + 2)
The answer is $_x.
Did you miss it?
#! Where were you born
u: (where * you * born) # bad- harder to read
I was born in San Francisco near the old church on the hill. I was born an
only child but my parents always wanted more.
#! Where were you born
u: (where * you * born) # good
I was born in San Francisco near the old church on the hill.
I was born an only child but my parents always wanted more.</code></pre>
<p><em>Rationale</em>:<br> Multiple sentence user output is harder to read if on the same line since they will tend to run into very long lines.</p>
<p>Code is certainly harder to understand when multiple actions are on the same line. On the other hand if the output is tiny, you might put it on a single line like this:</p>
<pre><code>u: (test) OK. $status += 1</code></pre>
<h2 id="bundle-related-rules">Bundle related rules</h2>
<ul>
<li>Put related rules in topics</li>
<li>Put more closely related rules together when you can.</li>
</ul>
<p>Examples:</p>
<pre><code>topic: ~aliens()
...
topic: ~family()
#!x*** Parents
#! Who is your mother
?: ( who * mother) Mom.
#! What does your mother do?
?: ( what * mother * do) She works.
#! Who is your father # note we had all mother stuff together before father
?: ( who * father) Dad.
#! What does your father do?
?: ( what * father * do) He works.
#!x*** Siblings
...</code></pre>
<p><em>Rationale</em>:<br> With appropriate bundling you should immediately know where to add a new rule or discover that you have multiple rules doing the same job.</p>
<p>I even annotate clusters of rules for <code>:abstract</code> using <code>#!x</code> comments which will reflect into the abstract to label the cluster and make it easy for people to follow along. The only problem may be when some earlier rule blocks a later one and you need to move something around. Consider using <code>!</code> keywords as instead.</p>
<h2 id="concept-and-function-localization">Concept and Function localization</h2>
<ul>
<li>If a concept or function is only used in 1 file, put it into that file.</li>
<li>If a concept or function is used in multiple places, use a global functions.top or concepts.top.</li>
<li>For tables used only used in 1 file, depends on size of table.</li>
</ul>
<p><em>Rationale</em>:<br> When you can localize data to the one file that uses it, it makes it easier to find the definition when you want to inspect it.</p>
<h2 id="keyword-casing-and-misspellings">Keyword Casing and Misspellings</h2>
<p>Use standard dictionary casing (or product owner's casing in the case of new non-words in the language) for keywords in concepts or patterns.</p>
<p>Avoid putting misspellings in concepts or keywords. Use replace: in your scripts file to effectively add additions to the predefined substitutions files that come with ChatScript.</p>
<p>But use <code>:replace</code> only when the misspell has only one possible obvious value. <code>replace:</code> changes the dictionary for ALL BOTS.! For misspellings which are legal words, add them to concepts or keywords.</p>
<p>Examples:</p>
<pre><code>concept: ~protocols (Blu-ray WiFi)
replace: blue_ray Blu-ray # true always. Do this as the correct spelling
replace: MS Microsoft # bad - computers true, medical not
#! I used my brakes
u: ([brake break]) Don’t hit the brakes too hard. # misspell is a real word, list it
#! I like mars
u: (_~planets) ‘_0 # outputs Mars even though user typed mars
#! Do you like sheep?
u: ([sheep shep sheap]) I like sheep # generally bad to do this</code></pre>
<p><em>Rationale</em>:<br> If a word exists with only one casing in the dictionary, CS can automatically adjust the input to make it correct. Even if a word exists in multiple cases, if a concept set has it in only one casing (e.g. <code>~planets</code> has the noun Mars and not the verb mars), if you memorize it, CS can memorize the correct casing.</p>
<p>Sometimes you expect some user typos. Putting the illegal forms in your patterns (like shep), means they enter the dictionary as acceptable words. This means spelling correction can change “misspellings” of misspellings, causing word drift for an input like “hep”. Prefer to use <code>replace:</code> if a misspelling can only go to one obvious place.</p>
</body>
</html>