anewt-developers team mailing list archive

[noreply@xxxxxxxxxxxxx]

------------------------------------------------------------
revno: 1812
committer: Wouter Bolsterlee <uws@xxxxxxxxx>
branch nick: anewt
timestamp: Sun 2010-11-28 21:29:10 +0100
message:
  Update and expand HACKING file
modified:
  HACKING


--
lp:anewt
https://code.launchpad.net/~uws/anewt/anewt.uws

Your team Anewt developers is subscribed to branch lp:anewt.
To unsubscribe from this branch go to https://code.launchpad.net/~uws/anewt/anewt.uws/+edit-subscription

=== modified file 'HACKING'
--- HACKING	2009-04-12 21:37:42 +0000
+++ HACKING	2010-11-28 20:29:10 +0000
@@ -7,20 +7,40 @@
 
     diff -u file.orig file.new > fix-some-problem.patch
 
-If you're a Bazaar user: bzr diff produces correct results. You're also
-welcome to put a Bazaar branch online, so that we can merge your changes.
-Even more useful are the bzr bundles instead of patches. Type 'bzr help
-bundle' for more information.
+If you're a Bazaar user: bzr diff produces correct results. Even more useful
+are the bzr bundles instead of patches. Type 'bzr help bundle' for more
+information. You're also welcome to put a Bazaar branch online, so that we can
+merge your changes.
+
+Happy hacking!
 
 
 Coding style
 ============
 
+Note: this is not an exhaustive list. Look at the source for more examples.
+
+
+General conventions
+-------------------
+
 Always use UNIX-style line endings, i.e. only \n, not \r\n.
 
-We use single tabs for indentation. That means tabs. Tabs. TABS! (Yes, this
+Always include a closing ?> php marker in each file.
+
+
+Indentation
+-----------
+
+Use single tabs for indentation. That means tabs. Tabs. TABS! (Yes, this
 file has 4 spaces instead of tabs, but hey, this is not a .php file.)
 
+Always indent your code correctly (see also below).
+
+
+Naming conventions
+------------------
+
 Class names start with a capital letter:
 
     class Foo extends Bar
@@ -31,18 +51,20 @@
 reasons some Anewt class names do not start with "Anewt", but that might be
 fixed some day in the future (but it involves heavy API breakage).
 
+Prefix all classes with the module name, e.g. AnewtForm* for all classes inside
+the form module. Use a sensible mix of prefixing and suffixing for class
+hierarchies, e.g. AnewtFormControl for the base class and
+AnewtFormControl{Text,Choice,...} for the specific subclasses.
 
 Method names always use lowercase letters and underscores:
 
     function do_something($foo, $bar)
 
-
 Variable names use lowercase letters and underscores:
 
     var $some_data;
     var $some_other_data;
 
-
 No strange prefixing or suffixing anywhere:
 
     /* wrong */
@@ -53,10 +75,13 @@
     var $foo = 3;
 
 
+Braces, parentheses, ...
+------------------------
+
 Opening braces should be placed on a separate line. For control structures
 (if(), while(), for(), foreach() and switch()) you may also place the opening
 brace at the end of the same line, but only if that improves legibility, e.g.
-for two-line if() statements. For one-line if() statements the braces may be
+for two-line if() statements. For one-line if() statements the braces must be
 omitted altogether, but if you decide to add some code comments, you should
 always add braces for clarity.
 
@@ -64,7 +89,8 @@
     {
         function do_something()
         {
-            if (some_condition()) {  /* The { may be on the next line as well */
+            if (some_condition())
+            {  /* The { may be on the next line as well */
                 first();
                 second();
                 third();
@@ -75,6 +101,9 @@
     }
 
 
+Whitespace
+----------
+
 No whitespace before parentheses, except for control structures:
 
     /* wrong */
@@ -87,11 +116,14 @@
     while (some_condition_holds())
 
 
+Assertions and exceptions
+-------------------------
+
 Use assertions to check for coding errors. Don't use assertions for run-time
 failures that should NOT cause execution to be aborted:
 
     function first_char($str)
-	{
+    {
         /* Not passing a string is a programming error: */
         assert('is_string($str)');
 
@@ -102,25 +134,41 @@
         return $str[0];
     }
 
+Throw exceptions for recoverable errors. Make sure to create proper
+AnewtException subclasses.
+
+
+Comments and documentation blocks
+---------------------------------
+
 The code uses Doxygen-style comments, and each class, function, and member
-variable must be documented. Additional comments written inside the code should
-always use the /* ... */ syntax, and never the // or # syntax. Comment example:
-
-	/**
-	  * Frobnicate the passed string value.
-	  *
-	  * \param $bar
-	  *   The value to frobnicate
-	  *
-	  * \return
-	  *    The frobnicated value
-	  */
-	function foo($bar)
-	{
-		/* These are some code comments */
-		return $bar;
-	}
-
+variable must be documented:
+
+    /**
+      * Frobnicate the passed string value.
+      *
+      * \param $bar
+      *   The value to frobnicate
+      *
+      * \return
+      *    The frobnicated value
+      */
+    function foo($bar)
+    {
+        /* These are some code comments */
+        return $bar;
+    }
+
+
+Additional comments written inside the code should always use the /* ... */
+syntax, and never the // or # syntax.
+
+Comments should (almost) always be put on their own line.
+
+
+
+String literals
+---------------
 
 Some notes regarding string literals:
 - always use single quotes for literal string values, except if you need tab or
@@ -130,6 +178,5 @@
   sprintf('foo %s', $bar)
 
 
-Look at the source for more examples.
 
-Happy hacking!
+# vim: tabstop=4 shiftwidth=4 expandtab