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
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title> Dillo Web Browser ::
Naming & Coding
</title>
<style type="text/css">
body {margin: 0}
.sidebar .items {background: #f8f8f8}
.sidebar h3 {font-size: 1em; margin: 0.4em 0 0.2em 0}
h1 {color: #67f; margin-top: 0.25em; margin-bottom: 0.25em}
h3 {color: #56f; background: #f0f0f0}
.section {background: #f8f8f8; border-color: #e8e8e8; border-style: solid; border-width: 1px; margin-bottom: 0.5em}
.section h3 {margin-top: 0; margin-bottom: 0.2em}
ul li {list-style-type: square}
</style>
</head>
<body text="black" link="blue" vlink="#403090" bgcolor="white"
style="line-height: 1.3">
<table width="100%" cellspacing="0" cellpadding="0"><tr>
<td><img src="db1.png" alt="The Dillo Web Browser">
<td width="100%">
<img src="db2.png" alt="The Dillo Web Browser" height="124" width="100%">
</table>
<table border="0" cellpadding="15" cellspacing="5" width="100%">
<tr valign="top">
<td class="sidebar">
<h3>Dillo</h3>
<div class="items">
<a href="index.html">Home</a><br>
<a href="screenshots/index.html">Screenshots</a><br>
<a href="download.html">Download</a><br>
<a href="FAQ.html" title="Frequently asked questions">FAQ</a><br>
<a href="Compatibility.html">Compatibility</a><br>
<a href="http://hg.dillo.org/dillo/raw-file/default/ChangeLog">
Changelog</a><br>
<a href="Plans.html">Current Plans</a><br>
<a href="MList.html">Mailing List</a><br>
<a href="conferences.html">Conferences</a><br>
<a href="donations.html">Donate</a><br>
</div>
<h3>Users</h3>
<div class="items">
<a href="dillo3-help.html">Help</a><br>
<a href="Icons/index.html">Icons</a><br>
<a href="help/bug_meter.html">Bug meter</a><br>
<br>
</div>
<h3>Bug Tracker</h3>
<div class="items">
<small>[currently broken]</small><br>
<!--
<a href="/bugtrack/Dbugtrack.html">Bug Track Intro</a><br>
<a href="/bugtrack/Dquery.html">View Entries</a><br>
<a href="/bugtrack/Dinsert.html">Bug Insertion</a><br>
<a href="/bugtrack/Dvolunteer.html">Volunteering</a><br>
-->
</div>
<h3>Developers</h3>
<div class="items">
<a href="developer.html">New Developer</a><br>
<a href="documentation.html">Documentation</a> *<br>
<a href="NC_design.html">Naming&Coding</a><br>
<a href="source.html">Source repository</a><br>
<a href="dpi1.html">Dpi1 Spec</a><br>
<a href="CSS.html">CSS Spec</a><br>
<a href="D_authors.html">Authors</a><br>
<a href="authors/jcid-email.html">Security contact</a><br>
</div>
<h3>Related</h3>
<div class="items">
<a href="press.html">Dillo in the Press!</a><br>
<a href="interview.html">Interview</a><br>
<a href="interview.es.html">Entrevista</a>
<img src="chile.png" alt="*"><br>
<a href="Links.html">Links</a><br>
<a href="logos/logos.html">Art</a><br>
</div>
<p>
<a href="authors/webmaster-email.html">Webmaster</a>
<p>
<a href="http://www.anybrowser.org/campaign/">
<img src="abblue.gif" width="80" height="15"
alt="anybrowser"></a>
<td valign="top" align="left" width="100%">
<div lang=en>
<h1>Naming&Coding design</h1>
<p> Dillo's code is divided into modules. For instance: bookmark, cache,
dicache, gif.
<p>Let's think of a module named "menu", then:
<ul>
<li> Every internal routine of the module, should start with "Menu_"
prefix. </li>
<li> "Menu_" prefixed functions are not meant to be called from outside
the module. </li>
<li> If the function is to be exported to other modules (i.e. it will be
called from the outside), it should be wrapped with an "a_"
prefix. </li>
</ul>
<p> For instance: if the function name is "Menu_create", then it's an
internal function, but if we need to call it from the outside, then it
should be renamed to "a_Menu_create".
<p> Why the "a_" prefix? <br>
<br> Because it reads better "a_Menu_create" than "d_Menu_create" cause the
first one suggests "a Menu create" function!
<p> Another way of understanding this is thinking of "a_" prefixed functions
as Dillo's internal library, and the rest ("Menu_" prefixed in our
example) as a private module-library.
<div class=section>
<h3>Indentation</h3>
<p>Source code must be indented with 3 blank spaces, no
Tabs.<br> Why?<br> Because different editors expand or treat tabs in
several ways; 8 spaces being the most common, but that makes code really
wide, and we want to keep it within the 80 columns bounds (printer
friendly).
<p>You can use:
<code>indent -kr -sc -i3 -bad -nbbo -nut -l79 myfile.c</code>
</div>
<div class=section>
<h3>Function commenting</h3>
<p> Every single function of the module should start with a short comment
that explains its purpose; three lines should be enough, but if you
think it requires more, enlarge it.
<pre>
/*
* Try finding the url in the cache. If it hits, send contents
* from there. If it misses, set up a new connection.
*/
int a_Cache_open_url(const char *url, void *Data)
{
...
...
...
}
</pre>
We also have the <b>BUG:</b>, <b>TODO:</b> and <b>WORKAROUND:</b> tags.<br>
Use them within
source code comments to spot hidden issues. For instance:
<pre>
/* BUG: this counter is not accurate */
++i;
/* TODO: get color from the right place */
a = color;
/* WORKAROUND: the canonical way of doing it doesn't work yet. */
++a; ++a; ++a;</pre>
</div>
<div class=section>
<h3>Function length</h3>
<p>Let's try to keep functions within the 45 lines boundary. This eases code
reading, following, understanding and maintenance.
</div>
<div class=section>
<h3>Functions with a single exit</h3>
<p>It's much easier to follow and maintain functions with a single
exit point at the bottom (instead of multiple returns). The
exception to the rule are calls like dReturn_if_fail() at its head.
</div>
<div class=section>
<h3>dlib Functions</h3>
<ul>
<li> Dillo uses its own <b>dlib</b> library extensively.
Before starting to code something
new, a good starting point is to check what this library has to
offer (check <code>dlib/dlib.h</code>).</li>
<li> Memory management must be done using <code>dNew, dNew0, dMalloc,
dFree</code> and their relatives.</li>
<li> For debugging purposes and error catching (not for normal flow):
<code>dReturn_if_fail, dReturn_val_if_fail</code>
etc. are encouraged.</li>
<li> The <code>MSG</code> macro is extensively used to output additional
information to the calling terminal.</li>
</ul>
</div>
<div class=section>
<h3>C++</h3>
Source code in C++ should follow the same rules with these exceptions:
<ul>
<li>Class method names are camel-cased and start with lowercase<br>
e.g. appendInputMultipart
<li>Classes and types start uppercased<br>
e.g. class DilloHtmlReceiver
<li>Class methods don't need to prefix its module name<br>
e.g. links->get()
</ul>
We also try to keep the C++ relatively simple. Dillo does use inheritance
and templates, but that's about all.
</div>
<div class=section>
<h3>What do we get with this?</h3>
<ul>
<li> A clear module API for Dillo; every function prefixed "a_" is to be
used outside the module.</li>
<li> A way to identify where the function came from (the capitalized
word is the module name).</li>
<li> An inner ADT (Abstract data type) for the module that can be isolated,
tested and replaced independently.</li>
<li> A two stage instance for bug-fixing. You can change the exported
function algorithms while someone else fixes the internal
module-ADT!</li>
<li> A coding standard ;)</li>
</ul>
</div>
<h6> Naming&Coding design by Jorge Arellano Cid</h6>
</div>
</td>
</tr>
</table>
</body>
</html>
|
