344
edits
Changes
Development Team/Code guidelines (view source)
Revision as of 13:46, 9 November 2010
, 13:46, 9 November 2010→Miscellaneous: add guidelines on strings, highlight code, add hint on string logging
== Miscellaneous ==
== Miscellaneous ==
* Use logging.debug('foo %r bar', x) instead of logging.debug('foo %r bar' % x). This is more robust and formatting only happens if we actually log something.
* Use <code>logging.debug('foo %r bar', x)</code> instead of <code>logging.debug('foo %r bar' % x)</code>. This is more robust and formatting only happens if we actually log something.
* When logging strings, consider using <code>%r</code> instead of <code>%s</code> because <code>%r</code> will take care of quoting and escaping the string as needed
* When you catch an exception and want to log it, use logging.exception(), this will print the whole backtrace and exception information, which is very useful when debugging.
* When you catch an exception and want to log it, use logging.exception(), this will print the whole backtrace and exception information, which is very useful when debugging.
* "Short" string literals should use single quotes (<code>'</code>) unless the string contains a single quote (that would need to be escaped)
* "Long" string literals should use three double quotes (<code>"""</code>)
== Tools ==
== Tools ==
When possible use tools to check your code, this will save lots of time for everybody involved.
When possible use tools to check your code, this will save lots of time for everybody involved.
Please try to use [http://www.logilab.org/857 pylint] to verify your patch for things like exceeding 80 columns etc., unused imports and unused variables. Pylint is not a tool you can rely on 100%, but it helps to follow some guidelines and to avoid the most stupid errors like typos. To run it: "./sugar-jhbuild run pylint sugar jarabe".
Please try to use [http://www.logilab.org/857 pylint] to verify your patch for things like exceeding 80 columns etc., unused imports and unused variables. Pylint is not a tool you can rely on 100%, but it helps to follow some guidelines and to avoid the most stupid errors like typos. It gets called with the name of the (installed) Python module to check, e.g. for sugar:
./sugar-jhbuild build -n jarabe
./sugar-jhbuild run pylint jarabe
[http://github.com/cburroughs/pep8.py pep8.py] catches more style errors than pylint, so make sure to run that one, too.
You can also run it on individual files so you don't need to install first (doesn't work well for sugar-base and sugar-toolkit because they use the same module name):
./sugar-jhbuild run pylint source/sugar-datastore/src/carquinyol/*.py
[http://github.com/cburroughs/pep8.py pep8.py] catches more style errors than pylint, so make sure to run that one, too:
./sugar-jhbuild run pep8 --repeat source/sugar-datastore/src/carquinyol/*.py
In the sugar packages use 'make distcheck' to make sure all files are included and the POTFILES.in is up to date.
In the sugar packages use 'make distcheck' to make sure all files are included and the POTFILES.in is up to date.