Recent changes to TenCommandments

WikiPage TenCommandments modified by Adam Tauno Williams

Adam Tauno Williams — Wed, 13 Mar 2013 11:18:02 -0000

--- v6
+++ v7
@@ -9,3 +9,4 @@
 + Do not shell out to OS / shell commands unless you really have no other way to do something.  Using external commands creates a stealth dependency, a dependence on implementation details, and generating meaningful error messages, or even knowing something failed, is extremely difficult.
 + Long, descriptive, and highly detailed error messages are good.  Short and vague error messages are bad.  An exception message should describe what happened, and possibly why, and ___always___ involving what.  If you couldn't open a file: what file?  If you couldn't connect to a network resource: what network resource - as in what URL?  Stack traces are ___not___ error messages.  It is the error message text that should describe what went wrong, or at least what was unexpected.  When you are writing a block of code ___you___ the ___developer___ know what is going on - the user or administrator does not - so it is ___your responsibility___, as the developer, to illuminate the situation.
 + objectIds are __long__, not __int__.  So "int( string-of-object-id )" is incorrect;  the correct cast is "long( string-of-object-id )".  __Any casting of an objectId to int is a bug__.
++ Use the [patch queues](Patch Queues).  Making patches in the patch queue is better than many-commits to the code repo.  __Commit is not Save!__  A commit to the code repo should do a specific thing;  doing a specific thing should not be spread across many commits;  patch queues make that much easier.  It also makes it easier to attach patches to tickets/bugs, which is a virtuous behavior.

WikiPage TenCommandments modified by Adam Tauno Williams

Adam Tauno Williams — Wed, 13 Mar 2013 11:14:16 -0000

--- v5
+++ v6
@@ -8,3 +8,4 @@
 + Use the [BLOBManager] for file access;  creating, read, writing, etc.. of files.  For one thing the BLOBManager automatically manages files relative to the server's documentation root.  Nothing should be operating on files outside the document root except in very special circumstances.
 + Do not shell out to OS / shell commands unless you really have no other way to do something.  Using external commands creates a stealth dependency, a dependence on implementation details, and generating meaningful error messages, or even knowing something failed, is extremely difficult.
 + Long, descriptive, and highly detailed error messages are good.  Short and vague error messages are bad.  An exception message should describe what happened, and possibly why, and ___always___ involving what.  If you couldn't open a file: what file?  If you couldn't connect to a network resource: what network resource - as in what URL?  Stack traces are ___not___ error messages.  It is the error message text that should describe what went wrong, or at least what was unexpected.  When you are writing a block of code ___you___ the ___developer___ know what is going on - the user or administrator does not - so it is ___your responsibility___, as the developer, to illuminate the situation.
++ objectIds are __long__, not __int__.  So "int( string-of-object-id )" is incorrect;  the correct cast is "long( string-of-object-id )".  __Any casting of an objectId to int is a bug__.

WikiPage TenCommandments modified by Adam Tauno Williams

Adam Tauno Williams — Tue, 27 Nov 2012 20:43:10 -0000

--- v4
+++ v5
@@ -1,6 +1,8 @@
 [Development]
 
-#Ten Commandments Of OpenGroupware Coils Development
+#The Ten Commandments 
+
+Yep, it is just a name for a list of rules.  There may be slight more or less than 10 rules.  If you go read the original ten commandments you'll find they aren't exactly 10 rules either; so we have precedent for ball-park numbering.
 
 1. Use of the "os" module is evil.  Any "import os" line should include a justification.  Use of "os" almost always creates a dependency on implementation details. See commandment #2.
 + Use the [BLOBManager] for file access;  creating, read, writing, etc.. of files.  For one thing the BLOBManager automatically manages files relative to the server's documentation root.  Nothing should be operating on files outside the document root except in very special circumstances.

WikiPage TenCommandments modified by Adam Tauno Williams

Adam Tauno Williams — Tue, 27 Nov 2012 16:11:40 -0000

--- v3
+++ v4
@@ -5,3 +5,4 @@
 1. Use of the "os" module is evil.  Any "import os" line should include a justification.  Use of "os" almost always creates a dependency on implementation details. See commandment #2.
 + Use the [BLOBManager] for file access;  creating, read, writing, etc.. of files.  For one thing the BLOBManager automatically manages files relative to the server's documentation root.  Nothing should be operating on files outside the document root except in very special circumstances.
 + Do not shell out to OS / shell commands unless you really have no other way to do something.  Using external commands creates a stealth dependency, a dependence on implementation details, and generating meaningful error messages, or even knowing something failed, is extremely difficult.
++ Long, descriptive, and highly detailed error messages are good.  Short and vague error messages are bad.  An exception message should describe what happened, and possibly why, and ___always___ involving what.  If you couldn't open a file: what file?  If you couldn't connect to a network resource: what network resource - as in what URL?  Stack traces are ___not___ error messages.  It is the error message text that should describe what went wrong, or at least what was unexpected.  When you are writing a block of code ___you___ the ___developer___ know what is going on - the user or administrator does not - so it is ___your responsibility___, as the developer, to illuminate the situation.

WikiPage TenCommandments modified by Adam Tauno Williams

Adam Tauno Williams — Tue, 27 Nov 2012 15:17:23 -0000

--- v2
+++ v3
@@ -1,3 +1,5 @@
+[Development]
+
 #Ten Commandments Of OpenGroupware Coils Development
 
 1. Use of the "os" module is evil.  Any "import os" line should include a justification.  Use of "os" almost always creates a dependency on implementation details. See commandment #2.

WikiPage TenCommandments modified by Adam Tauno Williams

Adam Tauno Williams — Tue, 27 Nov 2012 15:16:42 -0000

--- v1
+++ v2
@@ -1,3 +1,5 @@
 #Ten Commandments Of OpenGroupware Coils Development
 
-1.
+1. Use of the "os" module is evil.  Any "import os" line should include a justification.  Use of "os" almost always creates a dependency on implementation details. See commandment #2.
++ Use the [BLOBManager] for file access;  creating, read, writing, etc.. of files.  For one thing the BLOBManager automatically manages files relative to the server's documentation root.  Nothing should be operating on files outside the document root except in very special circumstances.
++ Do not shell out to OS / shell commands unless you really have no other way to do something.  Using external commands creates a stealth dependency, a dependence on implementation details, and generating meaningful error messages, or even knowing something failed, is extremely difficult.

WikiPage TenCommandments modified by Adam Tauno Williams

Adam Tauno Williams — Tue, 27 Nov 2012 14:40:07 -0000

#Ten Commandments Of OpenGroupware Coils Development 1.