Escalation Coding Practices

Logging

• Formatting of messages in log should be done using '%s' instead of str.format() for example 

  log.exception(
   'Request sending to Software Secure failed for user %s, setting status to must_retry',
   self.user
  )

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 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. 

http://edx.readthedocs.io/projects/edx-developer-guide/en/latest/style_guides/python_guidelines.html#breaking-long-lines

Quality Tests

Someone may across a situation where jenkins/quality test fail 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 test. This flag skip 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 bokchoy test, catch is to NOT use --fasttest so assets are compiled again now with that changed file.