Repo and Code Guidelines

Repo Requests

Pushing

• You can push your personal work branches whenever you feel comfortable, but pushing to main or production is going to depend on the nature of the project. Make sure you and your collaborates have a system you agree to for how your repo is run, and stick to it.
• We’re not using git to track your progress, so it can be treated like a collaboration tool and a failsafe.

Usable for others

• When a project is done, other people can use it.
• This means including readmes, documentation, and release information.
• Documentation should include execution examples! You can do something like rework one of your work notebooks to show how your stuff works, and the basic execution.
• Larger projects should be using some sort of distribution tools (like poetry), so they can be put on places like pypi.

Coding Standards

This is a quick reference sheet, a longer form discussion can be found in this blogpost

Readable Code

• The key of writing good code is knowing it will be read more than it’s written, in most cases. Make it as clear and accessible as possible. Some of the best code you can write is code that is understandable without comments.
• Please work in either functional or OOP (“object oriented programing” …classes basically.) Long blocks of used-once code is often full of redundancies and hard to read. Additionally, mixing OOP and functional is also hard to read and follow.
• It's a little overkill in some cases, but do your best to try and follow pep8 (the python standard notation guidelines), to make everyone's life easier; link is here

Naming

• Thinking along the lines of this video for naming convention suggestions. I don’t agree with everything here but it’s not a bad start. Naming Things in Code
• The most important thing is to Stay Consistent and Stay Readable.
• The best advice I ever received for coding is “Write code like the person who will maintain it has a short temper, tight deadlines, and knows your phone number”

Docstrings and in code documentation

• Include doc strings (‘’’ words ‘’’ <- That guy) whenever it makes sense to (a large number of input variables, being used in outside packages, not totally clear output or process). If your code is not immediately readable, a written description should be included (but you should try to make it readable)
• Your doc strings should include a description of the input variables whenever you can.
• It also will describe the major purpose, or limitations
• Output is also described, with its type.
• (Python isn’t a typed language, please try your best to make it so people don’t need to call type(var) on everything returned by your functions)

Safe to Import

• Have you ever imported a package and it does just a ton of work in the background before actually importing? Or just printed a bunch of stuff all over your screen? Yeah super annoying.
• if working in .py files, include your execution in an if __name__== ”__main__:” block. This prevents code from being executed when it is simply imported from one file to another. This is basically a block at the end of a script that runs everything you want someone to be able to do if they run this script. Putting in this “if” block prevents the full execution of the code being included if someone imports script into a different file. Basically, it makes your code more useful, so you won’t have to rewrite functions if you already have them somewhere else.
• Quick worked example:

File 1: dont_do_something.py:

 class DoSomething:
 	def do_something():
 		print(“Does Something”)
 if __name__ == “__main__”:
 	`DoSomething.do_something()

When run directly, will print Does Something

File 2: import_dont_do_something.py

import dont_do_something

When run will do...nothing.

File 3: do_something.py

 class DoSomething:
	def do_something():
		print(“Does Something”)
 DoSomething.do_something()

When run directly, will print Does Something

File 3: import_do_something.py

import do_something

When run, even though there's no execution code, just a single import statement, will print Does Something.

---

• You can find a great long form explainer for why this happens in this thread

Tested

• Your code should...work. Not the first time its written for sure, but when released to the world, there needs to be checks in place that make sure it does what it says it does. This is where unit tests come in.
• Unit tests take individual piece of code, and test it in various circumstances. They should cover the majority of possibilities for how your code will be run.
• Because python is not a compiled language, just running your code is not making sure every part of it works. Unit tests should cover each part of your if/else loops, and check that errors are thrown that are expected to be thrown, and any intended behavior is working as described.
• A good way to start writing test cases is to think about how your code fits together, and write a function that checks that steps between each section and verifies that what you think is happening is actually happening.
• Recommended file structure:

>Project 
 ->project
  --> foo.py
 ->test
  --> foo_test.py

• We recommend using the pytest framework as a test case runner.
• A quick pytest example:

def func(x): 
   return x+1

def test_func(): 
  test_input = 5
  expected_output = 6 
  assert func(test_input) == expected_output