Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Added the pocoo styleguide to the documentation

  • Loading branch information...
commit 793a56bc8b3a42601f0d3e9b6a1f0f73a9c31c33 1 parent e84ca8e
Armin Ronacher authored
Showing with 201 additions and 0 deletions.
  1. +1 −0  docs/contents.rst.inc
  2. +200 −0 docs/styleguide.rst
1  docs/contents.rst.inc
View
@@ -44,6 +44,7 @@ Design notes, legal information and changelog are here for the interested.
security
unicode
extensiondev
+ styleguide
upgrading
changelog
license
200 docs/styleguide.rst
View
@@ -0,0 +1,200 @@
+Pocoo Styleguide
+================
+
+The Pocoo styleguide is the styleguide for all Pocoo Projects, including
+Flask. This styleguide is a requirement for Patches to Flask and a
+recommendation for Flask extensions.
+
+In general the Pocoo Styleguide closely follows :pep:`8` with some small
+differences and extensions.
+
+General Layout
+--------------
+
+Indentation:
+ 4 real spaces. No tabs, no exceptions.
+
+Maximum line length:
+ 79 characters with a soft limit for 84 if absolutely necessary. Try
+ to avoid too nested code by cleverly placing `break`, `continue` and
+ `return` statements.
+
+Continuing long statements:
+ To continue a statement you can use backslashes in which case you should
+ align the next line with the last dot or equal sign, or indent four
+ spaces::
+
+ this_is_a_very_long(function_call, 'with many parameters') \
+ .that_returns_an_object_with_an_attribute
+
+ MyModel.query.filter(MyModel.scalar > 120) \
+ .order_by(MyModel.name.desc()) \
+ .limit(10)
+
+ If you break in a statement with parentheses or brances, align to the
+ braces::
+
+ this_is_a_very_long(function_call, 'with many parameters',
+ 23, 42, 'and even more')
+
+ For lists or tuples with many items, break immediately after the
+ opening brace::
+
+ items = [
+ 'this is the first', 'set of items', 'with more items',
+ 'to come in this line', 'like this'
+ ]
+
+Blank lines:
+ Top level functions and classes are separated by two lines, everything
+ else by one. Do not use too many blank lines to separate logical
+ segments in code. Example::
+
+ def hello(name):
+ print 'Hello %s!' % name
+
+
+ def goodbye(name):
+ print 'See you %s.' % name
+
+
+ class MyClass(object):
+ """This is a simple docstring"""
+
+ def __init__(self, name):
+ self.name = name
+
+ def get_annoying_name(self):
+ return self.name.upper() + '!!!!111'
+
+Expressions and Statements
+--------------------------
+
+General whitespace rules:
+ - Whitespace is absend for unary operators that are not works
+ (eg: ``-``, ``~`` etc.) as well on the inner side of parentheses.
+ - Whitespace is placed between binary operators.
+
+ Good::
+
+ exp = -1.05
+ value = (item_value / item_count) * offset / exp
+ value = my_list[index]
+ value = my_dict['key']
+
+ Bad::
+
+ exp = - 1.05
+ value = ( item_value / item_count ) * offset / exp
+ value = (item_value/item_count)*offset/exp
+ value=( item_value/item_count ) * offset/exp
+ value = my_list[ index ]
+ value = my_dict ['key']
+
+Yoda statements are a nogo:
+ Never compare constant with variable, always variable with constant:
+
+ Good::
+
+ if method == 'md5':
+ pass
+
+ Bad::
+
+ if 'md5' == method:
+ pass
+
+Comparisons:
+ - against arbitary types: ``==`` and ``!=``
+ - against singletones with ``is`` and ``is not`` (eg: ``foo is not
+ None``)
+ - never compare something with `True` or `False` (for example never
+ do ``foo == False``, do ``not foo`` instead)
+
+Negated containment checks:
+ use ``foo not in bar`` instead of ``not foo in bar``
+
+Instance checks:
+ ``isinstance(a, C)`` instead of ``type(A) is C``, but try to avoid
+ instance checks in general. Check for features.
+
+
+Naming Conventions
+------------------
+
+- Class names: ``CamelCase``, with acronyms kept uppercase (``HTTPWriter``
+ and not ``HttpWriter``)
+- Variable names: ``lowercase_with_underscores``
+- Method and functin names: ``lowercase_with_underscores``
+- Constants: ``UPPERCASE_WITH_UNDERSCORES``
+- precompiled regular expressions: ``name_re``
+
+Protected members are prefixed with a single underscore. Double
+underscores are reserved for mixin classes.
+
+On classes with keywords, trailing underscores are appended. Clashes with
+builtins are allowed and **must not** be resolved by appending an
+underline to the variable name. If the function needs to access a
+shadowed builtin, rebind the builtin to a different name instead.
+
+Function and method arguments:
+ - class methods: ``cls`` as first parameter
+ - instance methods: ``self`` as first parameter
+ - lambdas for properties might have the first parameter replaced
+ with ``x`` like in ``display_name = property(lambda x: x.real_name
+ or x.username)``
+
+
+Docstrings
+----------
+
+Docstring conventions:
+ All docstrings are formatted with reStructuredText as understood by
+ Sphinx. Depending on the number of lines in the docstring, they are
+ layed out differently. If it's just one line, the closing tripple
+ quote is on the same line as the opening, otherwise the text is on
+ the same line as the opening quote and the tripple quote that closes
+ the string on its own line::
+
+ def foo():
+ """This is a simple docstring"""
+
+
+ def bar():
+ """This is a longer docstring with so much information in there
+ that it spans three lines. In this case the closing tripple quote
+ is on its own line.
+ """
+
+Module header:
+ The module header consists of an utf-8 encoding declaration (if non
+ ASCII letters are used, but it is recommended all the time) and a
+ standard docstring::
+
+ # -*- coding: utf-8 -*-
+ """
+ package.module
+ ~~~~~~~~~~~~~~
+
+ A brief description goes here.
+
+ :copyright: (c) YEAR by AUTHOR.
+ :license: LICENSE_NAME, see LICENSE_FILE for more details.
+ """
+
+ Please keep in mind that proper copyrights and license files are a
+ requirement for approved Flask extensions.
+
+
+Comments
+--------
+
+Rules for comments are similar to docstrings. Both are formatted with
+reStructuredText. If a comment is used to document an attribute, put a
+colon after the opening pound sign (``#``)::
+
+ class User(object):
+ #: the name of the user as unicode string
+ name = Column(String)
+ #: the sha1 hash of the password + inline salt
+ pw_hash = Column(String)
Please sign in to comment.
Something went wrong with that request. Please try again.