Good coding guidelines tips

Coding Best Practices

• If you cannot see all the code of a function at one time, it is too big - break it up into smaller functions. Anything longer than 30 lines is suspect.
• Make each function carry out one specific job.
  • You can often tell if it is doing this when you try to name it. Things like "get_matched_regex" or "read_settings". If you are having trouble naming it other than using vague terms like "process_data" or having to use multiple verbs ("match_regex_and_read_and_process_file") then you should refactor.
• Function, class, variable, parameter naming.
  • Naming clarity
    • Don't use generic terms like "process_data", "file", "var", "x"
    • Give descriptive names like "match_result", "col_name", etc.
    • Don't be afraid of long names - remember code is written once but read many times, your extra keystrokes when creating something will be very helpful in a few weeks, months, years when you or someone else is trying to understand what's going on.
    • Using descriptive names helps in debugging/testing and general understanding of the code
  • Use UPPER_CASE names for constants defined at the module level
  • Use _func_name for constants, module functions, class methods and member variables if the item should not be used outside of the module/class.
• Commenting
  • Code structure and naming should be clear enough that you shouldn't need comments
  • Use comments to explain something non-obvious (like potential return val from a function), not to explain obscure and lengthy code constructs
• Beware of literal values:
  • Should they really be parameters?
  • If you're using a literal 3 or more times, you should prob define it as a constant or local variable.
• Avoid using classes unless you need to keep state related to the functionality - use functions and pass data as parameters.
• Do use classes if you have a lot of complex state.
  • If you find you are passing lots of data parameters between functions, it might be better implemented as a class with the data as private class variables.
  • Use classes if you want to expose operations on data but not the data structure itself.
• Beware of copy/paste
  • If you find yourself copying/pasting code blocks, it probably means that you haven’t structured the code properly. Think about refactoring
• Beware of deep nestings of branches/loops
  • Use guard clauses at the start of functions and loops

  for foo in bar:
      if foo == invalid:
          continue
      do_other_loop_stuff()

  • Rather than:

      for foo in bar: 
         if foo == valid:
            do_other_loop_stuff() 

• Use named tuples if you're returning a bunch of values from a function:

  from collections import namedtuple 
  MyResult = namedtuple("MyResult", "status, value, message, query") 
  def my_func(): 
      return MyResult(200, 1.589895, "Nice result", "select x from foo")

  • You can treat the named tuple like a tuple but also address the members by names print(result.value)