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.
_______________________________________________
Webware-devel mailing list
[EMAIL PROTECTED]
https://lists.sourceforge.net/lists/listinfo/webware-devel
