Initial revision

1 files changed, 80 insertions, 0 deletions

diff --git a/doc/NC_design.txt b/doc/NC_design.txt
new file mode 100644
index 00000000..6932b9cf
--- /dev/null
+++ b/doc/NC_design.txt
@@ -0,0 +1,80 @@
+
+     _________________________________________________________________
+   
+                             Naming&Coding design
+     _________________________________________________________________
+   
+   Dillo's code is divided into modules. For instance: bookmark, cache,
+   dicache, gif.
+   
+   Lets think of a module named "menu", then:
+     * Every internal routine of the module, should start with "Menu_"
+       prefix.
+     * "Menu_" prefixed functions are not meant to be called from outside
+       the module.
+     * 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.
+       
+   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".
+   
+   Why the "a_" prefix?
+   Because of historical reasons.
+   And it reads better "a_Menu_create" than "d_Menu_create" cause the
+   first one suggests "a Menu create" function!
+   
+   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.
+   
+   Indentation: Source code must be indented with 3 blank spaces, no Tabs.
+   Why?
+   Because different editors expand or treat tabs in several ways; 8
+   spaces being the most common, but that makes code really wide and
+   we'll try to keep it within the 80 columns bounds (printer friendly).
+   
+   Function commenting:
+   
+   Every single function of the module should start with a short comment
+   that explains it's purpose; three lines must be enough, but if you
+   think it requires more, enlarge it.
+
+/*
+ * Try finding the url in the cache. If it hits, send the contents
+ * to the caller. If it misses, set up a new connection.
+ */
+int a_Cache_open_url(const char *url, void *Data)
+{
+   ...
+   ...
+   ...
+}
+
+   We also have the BUG: and todo: tags.
+   Use them within source code comments to spot hidden issues. For
+   instance:
+
+/* BUG: this counter is not accurate */
+++i;
+
+/* todo: get color from the right place */
+a = color;
+     _________________________________________________________________
+   
+  What do we get with this?
+  
+     * A clear module API for Dillo; every function prefixed "a_" is to
+       be used outside the module.
+     * A way for identifying where the function came from (the
+       capitalized word is the module name).
+     * An inner ADT (Abstract data type) for the module. That can be
+       isolated, tested and replaced independently.
+     * A two stage instance for bug-fixing. You can change the exported
+       function algorithms while someone else fixes the internal
+       module-ADT!
+     * A coding standard ;)
+     _________________________________________________________________
+   
+        Naming&Coding design by Jorge Arellano Cid