Cleaned up Coding and style guides, improved contribs

CODING_STYLE.md

@@ -1,32 +1,34 @@
 # Evennia Code Style
 
-All code submitted or committed to the Evennia project should aim to
-follow the guidelines outlined in [Python PEP 8][pep8]. Keeping the code style
-uniform makes it much easier for people to collaborate and read the
-code.
+All code submitted or committed to the Evennia project should aim to follow the
+guidelines outlined in [Python PEP 8][pep8]. Keeping the code style uniform
+makes it much easier for people to collaborate and read the code.
 
 A good way to check if your code follows PEP8 is to use the [PEP8 tool][pep8tool]
 on your sources.
 
-## A quick list of code style points
+## Main code style specification
 
  * 4-space indentation, NO TABS!
  * Unix line endings.
+ * 100 character line widths
  * CamelCase is only used for classes, nothing else.
  * All non-global variable names and all function names are to be
    lowercase, words separated by underscores. Variable names should
    always be more than two letters long.
  * Module-level global variables (only) are to be in CAPITAL letters.
- * (Evennia-specific): Imports should normally be done in this order:
+ * Imports should be done in this order:
    - Python modules (builtins and standard library)
    - Twisted modules
    - Django modules
    - Evennia library modules (`evennia`)
    - Evennia contrib modules (`evennia.contrib`)
- * All modules, classes, functions and modules should have doc
-   strings formatted as described below
+ * All modules, classes, functions and methods should have doc strings formatted
+   as outlined below.
+ * All default commands should have a consistent docstring formatted as
+   outlined below.
 
-## Doc strings
+## Code Docstrings
 
 All modules, classes, functions and methods should have docstrings
 formatted with [Google style][googlestyle] -inspired indents, using
@@ -129,14 +131,18 @@ indents to be 4 spaces wide (no tabs!).
 Here are all the supported block headers:
 
 ```
-    Args/Keyword Args:
-        argname (freeform type): text
+    """
+    Args
+        argname (freeform type): Description endind with period.
+    Keyword Args:
+        argname (freeform type): Description.
     Returns/Yields:
-        type: text
+        type: Description.
     Raises:
-        Exceptiontype: text
+        Exceptiontype: Description.
     Notes/Note/Examples/Example:
-        freeform text
+        Freeform text.
+    """
 ```
 
 Parts marked with "freeform" means that you can in principle put any
@@ -152,43 +158,114 @@ documented.
 Note that
 
 ```
+"""
 Args:
-    argname (type, optional): text
+    argname (type, optional): Description.
+"""
 ```
 
 and
 
 ```
-Kwargs:
-   argname (type): text
+"""
+Keyword Args:
+   sargname (type): Description.
+"""
 ```
 
 mean the same thing! Which one is used depends on the function or
 method documented, but there are no hard rules; If there is a large
-`**kwargs` block in the function, using the `Kwargs:` block may be a
+`**kwargs` block in the function, using the `Keyword Args:` block may be a
 good idea, for a small number of arguments though, just using `Args:`
 and marking keywords as `optional` will shorten the docstring and make
 it easier to read.
 
-### Default Commands
+## Default Command Docstrings
 
-These represent a special case since Commands in Evennia use their
-class docstrings to represent the in-game help entry for that command.
-For the default look of Command class docstrings see instead
-[the default command documentation policy][command-docstrings].
+These represent a special case since Commands in Evennia use their class
+docstrings to represent the in-game help entry for that command.
 
-### Automatic docstring templating
+All the commands in the _default command_ sets should have their doc-strings
+formatted on a similar form. For contribs, this is loosened, but if there is
+no particular reason to use a different form, one should aim to use the same
+style for contrib-command docstrings as well.
 
-The Python IDE [Pycharm][pycharm] will generate Evennia-friendly
-docstring stubs automatically for you, but the default format is
-reStructuredText. To change it to Evennia's Google-style, follow
-[this guide][pycharm-guide].
+```python
+      """
+      Short header
 
-## Ask Questions!
+      Usage:
+        key[/switches, if any] <mandatory args> [optional] choice1||choice2||choice3
+
+      Switches:
+        switch1    - description
+        switch2    - description
+
+      Examples:
+        Usage example and output
+
+      Longer documentation detailing the command.
+
+      """
+```
+
+- Two spaces are used for *indentation* in all default commands.
+- Square brackets `[ ]` surround *optional, skippable arguments*.
+- Angled brackets `< >` surround a _description_ of what to write rather than the exact syntax.
+- Explicit choices are separated by `|`. To avoid this being parsed as a color code, use `||` (this
+will come out as a single `|`) or put spaces around the character ("` | `") if there's plenty of room.
+- The `Switches` and `Examples` blocks are optional and based on the Command.
+
+Here is the `nick` command as an example:
+
+```python
+      """
+      Define a personal alias/nick
+
+      Usage:
+        nick[/switches] <nickname> = [<string>]
+        alias             ''
+
+      Switches:
+        object   - alias an object
+        account   - alias an account
+        clearall - clear all your aliases
+        list     - show all defined aliases (also "nicks" works)
+
+      Examples:
+        nick hi = say Hello, I'm Sarah!
+        nick/object tom = the tall man
+
+      A 'nick' is a personal shortcut you create for your own use [...]
+
+        """
+```
+
+For commands that *require arguments*, the policy is for it to return a `Usage:`
+string if the command is entered without any arguments. So for such commands,
+the Command body should contain something to the effect of
+
+```python
+      if not self.args:
+          self.caller.msg("Usage: nick[/switches] <nickname> = [<string>]")
+          return
+```
+
+## Tools for auto-linting
+
+### black
+
+Automatic pep8 compliant formatting and linting can be performed using the
+`black` formatter:
+
+    black --line-length 100
+
+### PyCharm
+
+The Python IDE [Pycharm][pycharm] can auto-generate empty doc-string stubs. The
+default is to use `reStructuredText` form, however. To change to Evennia's
+Google-style docstrings, follow [this guide][pycharm-guide].
 
-If any of the rules outlined in PEP 8 or in the sections above doesn't
-make sense, please don't hesitate to ask on the Evennia mailing list
-or in the chat.
 
 
 [pep8]: http://www.python.org/dev/peps/pep-0008