From 4f31c2a5c6bef7876ccfd2830cac2a713cf37505 Mon Sep 17 00:00:00 2001 From: alquerci Date: Thu, 4 Sep 2014 16:56:17 +0200 Subject: [PATCH 01/10] Removed the convertion that a file should contain only one class On Python a file is a module and a module is the unit of reuse. --- CONVENTIONS.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONVENTIONS.md b/CONVENTIONS.md index 4e300f4..dc2867f 100644 --- a/CONVENTIONS.md +++ b/CONVENTIONS.md @@ -16,7 +16,7 @@ General ------- * Use classes as much as possible. -* A file SHOULD contain only one class (module == class). +* A file MAY contain one or many interdependent classes. * Each statement MUST end with a semicolon `;`. @@ -55,7 +55,7 @@ Example ```Python import sys; -from package.class_name import ClassName; +from package.module import FooClassName; class ClassName(): def __init__(self, arg1, arg2): From 6e84882b11405eee33036299969abc0f45973fea Mon Sep 17 00:00:00 2001 From: alquerci Date: Thu, 4 Sep 2014 17:30:46 +0200 Subject: [PATCH 02/10] Added interface specification to the coding standard --- CONVENTIONS.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/CONVENTIONS.md b/CONVENTIONS.md index dc2867f..253d03a 100644 --- a/CONVENTIONS.md +++ b/CONVENTIONS.md @@ -48,6 +48,7 @@ Classes * You can put an `Exception` definition at the end of a file if the file is the only one that uses that exception. * Every `Exception` class MUST end with `Exception`. +* Every `Interface` class MUST end with `Interface`. Example @@ -57,7 +58,15 @@ import sys; from package.module import FooClassName; -class ClassName(): + +class ClassNameInterface(): + """The ClassNameInterface provide some useful features""" + + def methodName(self): + """Public method""" + + +class ClassName(ClassNameInterface): def __init__(self, arg1, arg2): """Python magic method""" self.propertyName = "{1}".format("Public property"); From 9be5534245ae7c17fea6eb3fee30ac3cf3e810b1 Mon Sep 17 00:00:00 2001 From: alquerci Date: Thu, 4 Sep 2014 18:14:33 +0200 Subject: [PATCH 03/10] Improved the Pyhtondoc convention --- CONVENTIONS.md | 46 ++++++++++++++++++++++++++++++++++++---------- 1 file changed, 36 insertions(+), 10 deletions(-) diff --git a/CONVENTIONS.md b/CONVENTIONS.md index 253d03a..a093042 100644 --- a/CONVENTIONS.md +++ b/CONVENTIONS.md @@ -60,35 +60,61 @@ from package.module import FooClassName; class ClassNameInterface(): - """The ClassNameInterface provide some useful features""" + """The ClassNameInterface provide useful feature. - def methodName(self): - """Public method""" + This feature is very useful. + """ + + def methodName(self, bar, baz): + """This method do something. + + @param bar: . + @param baz: . + + @return: . + + @raise : . + """ class ClassName(ClassNameInterface): def __init__(self, arg1, arg2): - """Python magic method""" + """Python magic method. + + @param arg1: . + @param arg2: . + + """ self.propertyName = "{1}".format("Public property"); self._propertyName = arg1; # Protected property self.__propertyName = arg2; # Private property print(self.propertyName, end="", file=sys.stderr); - def methodName(self): - """Public method""" - pass; + def methodName(self, bar, baz): + """This public method do somthing. + + @param bar: . + @param baz: . + + @return: . + + @raise : . + """ def _methodName(self): - """protected method""" + """This is a protected method. + """ pass; def __methodName(self): - """private method""" + """This is a private method. + """ pass; class ClassNameException(Exception): - """A ClassName Exception""" + """A ClassNameException. + """ pass; ``` From 89b65be9c3af04c4b8a3d287dd7f5a491359d10f Mon Sep 17 00:00:00 2001 From: alquerci Date: Thu, 4 Sep 2014 19:49:21 +0200 Subject: [PATCH 04/10] Improved the coding standard example --- CONVENTIONS.md | 119 ++++++++++++++++++++++++++++--------------------- 1 file changed, 69 insertions(+), 50 deletions(-) diff --git a/CONVENTIONS.md b/CONVENTIONS.md index a093042..bbf0aed 100644 --- a/CONVENTIONS.md +++ b/CONVENTIONS.md @@ -51,79 +51,98 @@ Classes * Every `Interface` class MUST end with `Interface`. -Example -------- -```Python -import sys; - -from package.module import FooClassName; +String +------ +* Double quotes for text +* Single quotes for anything that behaves like an identifier +* Double quoted raw string literals for regexps +* Tripled double quotes for docstrings -class ClassNameInterface(): - """The ClassNameInterface provide useful feature. - This feature is very useful. - """ +Example +------- - def methodName(self, bar, baz): - """This method do something. +Since a picture - or some code - is worth a thousand words, here's a short example containing most features described below: - @param bar: . - @param baz: . +```Python +# -*- coding: utf-8 -*- +######################## BEGIN LICENSE BLOCK ######################## +# This file is part of the cygapt package. +# +# Copyright (C) 2002-2009 Jan Nieuwenhuizen +# 2002-2009 Chris Cormie +# 2012 James Nylen +# 2012-2014 Alexandre Quercia +# +# For the full copyright and license information, please view the +# LICENSE file that was distributed with this source code. +######################### END LICENSE BLOCK ######################### + +class BarInterface(): + """Coding standards demonstration. + """ - @return: . + def getValue(self): + """Gets a value. - @raise : . + @return: str The value """ +class FooBar(BarInterface): + """Coding standards demonstration. + """ -class ClassName(ClassNameInterface): - def __init__(self, arg1, arg2): - """Python magic method. + SOME_CONST = 42; - @param arg1: . - @param arg2: . + def __init__(self, dummy, bar=None): + """Constructor. + @param dummy: str Some argument description + @param bar: BarInterface Some argument description """ - self.propertyName = "{1}".format("Public property"); - self._propertyName = arg1; # Protected property - self.__propertyName = arg2; # Private property + assert isinstance(dummy, str); + assert None is bar or isinstance(bar, BarInterface); - print(self.propertyName, end="", file=sys.stderr); + # define a private property + self.__fooBar = bar.getValue() if bar else self.__transformText(dummy); - def methodName(self, bar, baz): - """This public method do somthing. + def getValue(self): + """Gets a value. - @param bar: . - @param baz: . + @return: str The value + """ + return self.__fooBar; - @return: . + def __transformText(self, dummy, options=None): + """Transformes the dummy following options. - @raise : . - """ + @param dummy: str Some argument description + @param options: dict Some argument description - def _methodName(self): - """This is a protected method. - """ - pass; + @return: str|None Transformed input - def __methodName(self): - """This is a private method. + @raise Exception: When unrecognized dummy option """ - pass; + assert isinstance(dummy, str); + assert None is options or isinstance(options, dict); -class ClassNameException(Exception): - """A ClassNameException. - """ - pass; + mergedOptions = { + 'some_default': "values", + 'another_default': "more values", + }; + if options : + mergedOptions.update(options); -``` + if True is dummy : + return; + if "string" == dummy : + if "values" == mergedOptions['some_default'] : + return dummy[:5]; -String ------- + return dummy.title(); -* Double quotes for text -* Single quotes for anything that behaves like an identifier -* Double quoted raw string literals for regexps -* Tripled double quotes for docstrings + raise Exception('Unrecognized dummy option "{0}"'.format(dummy)); + +``` From 6c1170f5db4402d2622ec3d401f4ea6bfc7ced4f Mon Sep 17 00:00:00 2001 From: alquerci Date: Thu, 4 Sep 2014 19:59:58 +0200 Subject: [PATCH 05/10] Removed the CS for define exceptions out of the dedicated module --- CONVENTIONS.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/CONVENTIONS.md b/CONVENTIONS.md index bbf0aed..b792d04 100644 --- a/CONVENTIONS.md +++ b/CONVENTIONS.md @@ -44,9 +44,7 @@ Classes TWO underscores `__` to indicate private visibility. * Property/Method names MUST start but not ending with ONE underscores `_` to indicate protected visibility. -* `exception` module SHOULD contain all `Exception` class. -* You can put an `Exception` definition at the end of a file - if the file is the only one that uses that exception. +* An `exception` module MUST contain all exception classes of the package. * Every `Exception` class MUST end with `Exception`. * Every `Interface` class MUST end with `Interface`. From dea36f6215294ae7091b24df8cc5e776d8284c89 Mon Sep 17 00:00:00 2001 From: alquerci Date: Thu, 4 Sep 2014 21:05:30 +0200 Subject: [PATCH 06/10] Improved coding standards --- CONVENTIONS.md | 94 ++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 68 insertions(+), 26 deletions(-) diff --git a/CONVENTIONS.md b/CONVENTIONS.md index b792d04..7b4a53d 100644 --- a/CONVENTIONS.md +++ b/CONVENTIONS.md @@ -12,52 +12,94 @@ interpreted as described in [RFC 2119][]. [PEP 257]: http://www.python.org/dev/peps/pep-0257/ -General -------- +Files +----- -* Use classes as much as possible. +* Code MUST use 4 spaces for indenting, not tabs. +* All Python files MUST use the Unix LF (line feed) line ending. +* All Python files MUST end with a single blank line. * A file MAY contain one or many interdependent classes. -* Each statement MUST end with a semicolon `;`. +* An `exception` module MUST contain all exception classes of a package. -Idioms ------- +Structure +--------- -* Use only format() method to formatting strings. -* `print` is a function. +* Each statement MUST end with a semicolon `;`; +* Add a single space after each comma delimiter; -Files ------ +* Add a comma after each sequence types (`dict`, `list`, ...) item in a multi-line + form, even after the last one; -* Code MUST use 4 spaces for indenting, not tabs. -* All Python files MUST use the Unix LF (line feed) line ending. -* All Python files MUST end with a single blank line. +* Add a blank line before `return` statements, unless the return is alone inside + a statement-group (like an `if` statement); +* Use classes as much as possible. -Classes -------- +* Declare public methods first, then protected ones and finally private ones. + The exceptions to this rule are the class constructor and the `setUp` and `tearDown` methods + of unittest tests, which SHOULD always be the first methods to increase readability; + +* Strings SHOULD be concatenated using the `format()` method; + +* Use `print()` as a function with `from __future__ import print_function;` + on top of the module; + + +Naming Conventions +------------------ + +* Use StydlyCaps for class names; + +* Use camelCase, not underscores, for variable, function and method names, arguments; -* Class names MUST be declared in `StudlyCaps`. -* Method names MUST be declared in `camelCase`. -* Property/Method names MUST start but not ending with - TWO underscores `__` to indicate private visibility. -* Property/Method names MUST start but not ending with - ONE underscores `_` to indicate protected visibility. -* An `exception` module MUST contain all exception classes of the package. -* Every `Exception` class MUST end with `Exception`. -* Every `Interface` class MUST end with `Interface`. +* Use underscores for option names and parameter names; +* Prefix abstract classes with `Abstract`. -String ------- +* Suffix interfaces with `Interface`; + +* Suffix exceptions with `Exception`; + +* Property and method names SHOULD NOT ending with an underscore `_`; + +* Prefix property and method names with `_` to indicate protected visibility; + +* Prefix property and method names with `__` to indicate private visibility; + +* Use lowercase alphanumeric characters and underscores for file names; + + +String Delimiters +----------------- * Double quotes for text + * Single quotes for anything that behaves like an identifier + * Double quoted raw string literals for regexps + * Tripled double quotes for docstrings +Documentation +------------- + +* Add EpyDoc blocks for all classes, methods, and functions; + +* Omit the `@return` tag if the method does not return anything; + +* The `@param`, `@return` and `@raise` annotations SHOULD only be used; + + +License +------- + +* Cyg-apt is released under the GNU GPL v3 license, and the license block has to be present + at the top of every Python file, before the first import. + + Example ------- From 73249def081958a7c8a33e62be907ffc3032c092 Mon Sep 17 00:00:00 2001 From: alquerci Date: Tue, 9 Sep 2014 15:02:44 +0200 Subject: [PATCH 07/10] Removed usage of an options parameters --- CONVENTIONS.md | 28 ++++++++++++++++------------ 1 file changed, 16 insertions(+), 12 deletions(-) diff --git a/CONVENTIONS.md b/CONVENTIONS.md index 7b4a53d..4ab1de0 100644 --- a/CONVENTIONS.md +++ b/CONVENTIONS.md @@ -154,31 +154,35 @@ class FooBar(BarInterface): """ return self.__fooBar; - def __transformText(self, dummy, options=None): + def __transformText( + self, + dummy, + some_default="values", + another_default="more values", + third_default="more and more values", + ): """Transformes the dummy following options. - @param dummy: str Some argument description - @param options: dict Some argument description + @param dummy: str Some argument description + @param some_default: str Some argument description + @param another_default: str Some long argument description + with some useful explication + @param third_default: str Some argument description @return: str|None Transformed input @raise Exception: When unrecognized dummy option """ assert isinstance(dummy, str); - assert None is options or isinstance(options, dict); - - mergedOptions = { - 'some_default': "values", - 'another_default': "more values", - }; - if options : - mergedOptions.update(options); + assert isinstance(some_default, str); + assert isinstance(another_default, str); + assert isinstance(third_default, str); if True is dummy : return; if "string" == dummy : - if "values" == mergedOptions['some_default'] : + if "values" == some_default : return dummy[:5]; return dummy.title(); From 7b489eaf778913385ef6c377629df17381861e23 Mon Sep 17 00:00:00 2001 From: alquerci Date: Tue, 9 Sep 2014 15:35:06 +0200 Subject: [PATCH 08/10] Fixed doc string aligning --- CONVENTIONS.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/CONVENTIONS.md b/CONVENTIONS.md index 4ab1de0..3100135 100644 --- a/CONVENTIONS.md +++ b/CONVENTIONS.md @@ -138,8 +138,8 @@ class FooBar(BarInterface): def __init__(self, dummy, bar=None): """Constructor. - @param dummy: str Some argument description - @param bar: BarInterface Some argument description + @param dummy: str Some argument description + @param bar: BarInterface Some argument description """ assert isinstance(dummy, str); assert None is bar or isinstance(bar, BarInterface); @@ -163,11 +163,11 @@ class FooBar(BarInterface): ): """Transformes the dummy following options. - @param dummy: str Some argument description - @param some_default: str Some argument description + @param dummy: str Some argument description + @param some_default: str Some argument description @param another_default: str Some long argument description with some useful explication - @param third_default: str Some argument description + @param third_default: str Some argument description @return: str|None Transformed input From 61309141f65d23265d2ff4d2d8b785dde40b7a25 Mon Sep 17 00:00:00 2001 From: alquerci Date: Tue, 9 Sep 2014 16:02:28 +0200 Subject: [PATCH 09/10] Fixed license abbreviation --- CONVENTIONS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONVENTIONS.md b/CONVENTIONS.md index 3100135..1824600 100644 --- a/CONVENTIONS.md +++ b/CONVENTIONS.md @@ -96,7 +96,7 @@ Documentation License ------- -* Cyg-apt is released under the GNU GPL v3 license, and the license block has to be present +* Cyg-apt is released under the GNU GPLv3 license, and the license block has to be present at the top of every Python file, before the first import. From 5b64dc69435570eea4a2f013d544d10a05828e43 Mon Sep 17 00:00:00 2001 From: James Nylen Date: Wed, 17 Sep 2014 11:50:30 -0500 Subject: [PATCH 10/10] English fixes --- CONVENTIONS.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/CONVENTIONS.md b/CONVENTIONS.md index 1824600..aa83f8b 100644 --- a/CONVENTIONS.md +++ b/CONVENTIONS.md @@ -29,13 +29,13 @@ Structure * Add a single space after each comma delimiter; -* Add a comma after each sequence types (`dict`, `list`, ...) item in a multi-line - form, even after the last one; +* For sequence types (`dict`, `list`, ...) in a multi-line form, add a comma + after each item, even the last one; * Add a blank line before `return` statements, unless the return is alone inside a statement-group (like an `if` statement); -* Use classes as much as possible. +* Use classes as much as possible; * Declare public methods first, then protected ones and finally private ones. The exceptions to this rule are the class constructor and the `setUp` and `tearDown` methods @@ -50,19 +50,19 @@ Structure Naming Conventions ------------------ -* Use StydlyCaps for class names; +* Use StudlyCaps for class names; -* Use camelCase, not underscores, for variable, function and method names, arguments; +* Use camelCase, not underscores, for variable, function, method, and argument names; * Use underscores for option names and parameter names; -* Prefix abstract classes with `Abstract`. +* Prefix abstract classes with `Abstract`; * Suffix interfaces with `Interface`; * Suffix exceptions with `Exception`; -* Property and method names SHOULD NOT ending with an underscore `_`; +* Property and method names SHOULD NOT end with an underscore `_`; * Prefix property and method names with `_` to indicate protected visibility; @@ -161,7 +161,7 @@ class FooBar(BarInterface): another_default="more values", third_default="more and more values", ): - """Transformes the dummy following options. + """Transforms the dummy following options. @param dummy: str Some argument description @param some_default: str Some argument description