diff options
| author | Rodrigo Arias Mallo <rodarima@gmail.com> | 2024-01-01 23:40:52 +0100 |
|---|---|---|
| committer | Rodrigo Arias Mallo <rodarima@gmail.com> | 2024-01-01 23:40:52 +0100 |
| commit | 5ea943a5e789222472e45864e119cf786498bfcd (patch) | |
| tree | ea307589de0fdb202474ad4d07c0bef7fe1c53e8 /old/NC_design.html | |
Import original dillo.org website into old/
Diffstat (limited to 'old/NC_design.html')
| -rw-r--r-- | old/NC_design.html | 257 |
1 files changed, 257 insertions, 0 deletions
diff --git a/old/NC_design.html b/old/NC_design.html new file mode 100644 index 0000000..8f97486 --- /dev/null +++ b/old/NC_design.html @@ -0,0 +1,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> + |