================================
Zwiki coding style and practices
================================

This is to explain/improve current practices and to collect guidelines
that help us.


File Layout
===========

See README for a list of documentation files.

Directory overview:

================ ==================================================
ZWiki/           main source files
 plugins/        functionality-adding plugins
  tracker/       zwiki issue tracker plugin
  rating/        zwiki page rating plugin
  latexwiki/     page types supporting LaTeX
  mathaction/    page types supporting math tools
 tools/          administrator command-line tools
 pagetypes/      standard zwiki page types
 Extensions/     external methods
 scripts/        example zope/zwiki scripts
 i18n/           translation files
 skins/          skin templates & skin-based content
  zwiki/         the standard zwiki skin for zope & plone
 wikis/          wiki templates
  basic/         the standard pages and scripts for a new wiki
 profiles/       CMF/Plone GenericSetup configuration
================ ==================================================

Currently,

- there is no separate tests directory. Each source file has a companion
  file with _tests appended to the name, in the same directory. This
  sometimes is cluttersome but it makes tests easier to find, grep, and
  makes plugin tests easier.

- similarly, there is no separate docs directory. Documentation files are
  kept in the most appropriate directory, with ALLCAPITALIZED names to
  make them stand out.

- most source files have capitalized names. Some newer files have
  lower-case names.


Documentation guidelines
========================

Most Zwiki documentation is kept in the http://zwiki.org wiki.
Developer-specific docs are under http://zwiki.org/DeveloperNotes.
Developer documentation is to some extent moving to files within the
codebase, like this file.  These typically use restructured text markup.
To browse these filesystem docs online, use http://zwiki.org/repos/ZWiki
or the darcsweb interface.  (See also: FILESYSTEM_VS_WIKI_DOCS)

We have the following kinds of in-code documentation:

- ALLCAPS documentation files in any directory, like this README

- File docstrings

- Class docstrings

- Method/function docstrings

- Comments

  - comments are sometimes used instead of the docstrings above. This may
    or may not be appropriate, I don't know.

  - a section heading within a file, class or method.

  - a short explanatory comment appended to a line of code. 

  - longer explanatory comments when necessary.

  The Zwiki code has a lot of chatty comments. Nowadays we should try to
  minimise their use eg by making them unnecessary or by using
  intention-revealing names.

- Names

  Names of directories, files, classes, methods, variables are where
  documentation meets code. They are perhaps our most powerful tool. :)

  Use clarifying and intention-revealing names wherever possible to
  minimise the need for other documentation.

  Choosing good names for small chunks of code helps us to build up our
  own mini-language (DSL) for Zwiki-building, which helps us to say more
  with less code.


Conciseness
-----------
Concise, not over-verbose, non-redundant docs are good. To help us write
better docs, we could try to follow this length guideline when possible:

 ================= =================================================
 doc files         any length
 file docstrings   one paragraph
 class docstrings  one paragraph
 method docstrings one sentence, plus one per argument, or as needed
 comments          one sentence or fragment, on one line
 ================= =================================================


Docstrings
----------

The first sentence should be a concise summary of the object's purpose.

Older docstrings follow the PEP guideline to separate the first line from
the rest with a blank line, but we have abandoned this to save vertical
space.

It may sometimes be ok to omit the line breaks at the docstring's start
and end if it doesn't hurt readability.

Describe method arguments and return values when needed. We might want to
come up with a standard haskellish way of noting the expected input and
output types and whether side effects are expected.


Code guidelines
===============

In general, it's best to follow, first, the current guidelines in this
file, second, the style of existing Zwiki code, and third, standard Python
best practices.


Vertical space is precious, use long lines
------------------------------------------

IMHO, vertical space is more valuable than horizontal space. It's more
valuable to see more lines on the screen than to see the full contents of
every line. Keeping lines within 80 characters can obscure the shape of
code constructs, especially with functional coding style, and also means
we are less likely to see the whole method at once. Long lines, even over
80 characters, may sometimes be preferable. 

This assumes you have your editor truncate long lines, not wrap them.  I
do this, and maximize the window when I need more visibility on the line
ends.


Message passing style, functional programming style, etc.
---------------------------------------------------------

The Zwiki codebase is influenced by Smalltalk. Eg: 

- we encapsulate state and behaviour as objects when that makes sense

- we break up code into many small methods with intention-revealing names
  to form an expressive domain-specific language.

- "tell, don't ask", ie just send messages, ignore what's returned. 
  We haven't used this and I don't know how it applies to us; it's
  something to think about.

Recent code is also influenced by functional programming. Eg: 

- we minimise the use of variables and the use of procedural/sequential
  code (do this, then that, then the other). Instead, we compose functions
  (/methods) where possible.

- we prefer referentially-transparent functions where possible (return
  value depends only on the arguments - no side effects).

Think "fewer moving parts". Variables, imperative sequenced instructions,
and side effects are often unnecessary.  When we cut them out, there is
less to break and the code is more reliable and more testable.


More about naming
-----------------

Try to give procedures (functions/methods with side effects) verb names.
Try to give variables and side-effect-free functions noun names.


Security
--------

To specify method permissions, we sometimes use explicit zope security
declarations, sometimes omit the docstring, and sometimes use the _
prefix. The latter two interfere with readability and should be phased
out. We probably want to move to an all methods private by default policy,
and explicity declare permissions on everything that we want to expose.


Imports
-------
Imports are usually at the start of the file and in three groups: python,
then zope, then zwiki imports.




.. 

 Local Variables:
 mode: rst
 End:
