[Webware-devel] Guidelines Summary

[Tavis R. <ta...@ca...>]

Hi, 
I think we should update the existing Style Guidelines and 
incorporate them into a Developers' Guide document (on the Wiki to 
start with).

The Developers Guide would:
   * provide a brief history of development
   * provide a philosophical perspective
   * provide a methodology (emphasizing testing)
   * provide a structural overview + guidelines
   * provide style guidelines
   * provide testing howto + guidelines
   * provide cvs howto + guidelines
   * provide howto + guidelines release 
   * provide version naming guidelines

Some of the content would be relevant to both application developers 
and component developers.

Your thoughts?

Here's a quick summary to complement what we've been discussing and 
what's already written up in the Style Guidelines:

Line wrapping
==============

docstrings --> what Chuck wrote

actual code --> preferably 80, but 90/100 is ok if you really can't 
fit it in 80 and don't want to wrap.

Docstring style contents
=============================
what Chuck wrote 

++

Don't repeat the name of the module, function, class, method that you 
are documenting in the docstring like """getStatus gets the status""".

Every module should have a docstring.  Its synopsis should be a one 
liner that starts with 'Provides ...'.

Every class should have a docstring.  

Every non-trivial method or function should have a docstring.  
Preferably trivial ones should as well.



Files, names, capitalization
==============================
DO
---
ModuleName.py
WebKit/SubPackage/ModuleName.py

ModuleName.publicModuleVar
ModuleName._privateModuleVar

ModuleName.publicModuleFunc()
ModuleName._privateModuleFunc()

ModuleName.CONSTANT
ModuleName.CONSTANT_WITH_EXTRA_WORDS

ModuleName.ClassName

ClassName.publicInstanceMeth()
ClassName._privateInstanceMeth()

ClassName._myIntanceVar
ClassName.myInstanceVar() returns _myIntanceVar
ClassName.setInstanceVar() sets _myIntanceVar

instanceOfClass
localVarName

ConfigSetting 

DON'T
------
modulename.py
moduleName.py
module_name.py
Module_Name.py

className
class_Name

ClassName.instanceVar

configSetting

WebKit.ASStreamOut
WebKit.ThreadedAppServer.TASASStreamOut

...

EXCEPTIONS AND MAYBE'S
-----------------------

ClassName.COMMAND_LINE_OPTION for classes that implement a command 
line interface (I've been using this one, but I'm not sure about it.)

In UnitTests and FunctionalTests:
    class BasicRequest_concurrentVersion(TestCase): pass
    class BasicRequest(TestCase):
        def test_testName(self): pass


OTHER COMMENTS
------

Only use double underscored names where absolutely necessary.  They 
are a pain in the ass when a class is subclassed in a way the 
original author didn't predict.  Single underscores are sufficient to 
warn people that something isn't guarenteed to be present in future 
versions.