Coding Practices
- Awais Jibran (Deactivated)
- Feanil Patel
External Resources
In specific to this document, there are following helpful documents which we should take a look.
Logging
- Formatting of messages in the log should be done using '%s' instead of str.format() for example
log.exception( u'Request sending to Software Secure failed for user %s, setting status to must_retry', self.user )
Log messages can be breakdown as follows.
log.info( ( u'Request sending to Software Secure failed for user %s, course: %s, course grade: %s,' u'has_active_enrollment: %s, passed: %s, is_whitelisted: %s' ), self.user, course.id, course_grade, has_active_enrollment, course_grade.passed, is_whitelisted, )
Import Statements Ordering
Recommendation for import statements in a django project are thoroughly described here. A brief summary is as follows.
Group of statements should be ordered as follows.
Future
Standard library
Third-party libraries
Other Django components
Local Django component
try/excepts
Keeping in mind
Sort lines in each group alphabetically by the full module name.
Place all import module statements before from module import objects in each section.
Use absolute imports for other Django components and relative imports for local components.
On each line, alphabetize the items with the uppercase items grouped before the lowercase items.
Break long lines using parentheses and indent continuation lines by 4 spaces. Include a trailing comma after the last import and put the closing parenthesis on its own line.
Use a single blank line between the last import and any module level code, and use two blank lines above the first function or class.
PyCharm's "Optimize Imports" command should help with this!
Syntax and Organization
Recommendations for syntax and organization are described on edX's python style guide with examples. Most related parts are summarized as follow.
4-space indents (no tabs)
Names like this: modules_and_packages, functions_and_methods, local_variables, GLOBALS, CONSTANTS, MultiWordClasses
Acronyms should count as one word: RobustHtmlParser, not RobustHTMLParser
Trailing commas are good: they prevent having to edit the last line in a list when adding a new last line. You can use them in lists, dicts, function calls, etc.
EXCEPT: we aren’t (yet) limiting code lines to 79 characters. Use 120 as a limit for the code. Please use 79 chars as a limit for docstring lines though, so that the text remains readable.
Docstrings
Recommendations for docstrings are also described in edX's python style guide with examples. Most related parts are summarized as follow.
Write docstrings for all modules, classes, and functions.
Always format docstrings using the multi-line convention, even if there’s only one line of content (see below).
Use three double-quotes for all docstrings.
Start with a one-line summary. If you can’t fit a summary in one line, think harder, or refactor the code.
Write in Sphinx-friendly prose style. Put backquotes around code names (variables, parameters, methods, etc).
Some useful links regarding this subject are:
http://sphinxcontrib-napoleon.readthedocs.org/en/latest/example_google.html
https://google-styleguide.googlecode.com/svn/trunk/pyguide.html?showone=Comments#Comments
Breaking Long Lines
This link provides the recommendations for breaking down code lines. If you have long lines, try to refactor it.
Quality Tests
Someone may across a situation where jenkins/quality test fails with no violations reported. In such case try running
paver run_eslint && diff-quality --violations=eslint
on local.
This command may help in finding out any violation missed out.
Bokchoy Tests
Change is js code
There is a flag --fasttest with which we usually run the test. This flag skips compiling of static assets, so previously compiled assets are used.
Static assets include js files too. If one wants to change js code and see its impacts on the bokchoy test, the catch is to NOT use --fasttest so assets are compiled again now with that changed file.