TenCommandments

[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.
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.
3. 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.
4. 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.
5. 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.
6. Use the 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.