research-to-production/salary/README.md

Salary Assessment App

Demonstration of an interactive web-application built in python. This example shows "a small amount of effort" exerted to ensure reproducibility and readability but ultimately lacks in overall user-friendliness.

Takeaways: Good reproducibility, passable style/formatting.

• Of particular note here is the executable run shell script which provides support for running the application using a docker image as well as simultaneously supporting native shell execution if docker is not in the system $PATH
• Note the style in which functions are written in app.py
  • There is a mixture of functions and procedural code, wide abuse of global variables, and a lot of messy plotting code. Is it readable overall?
  • The app's "state" is held in data.json, is saved in a human-readable format (as opposed to binary), and is small enough to be negligible
  • The functions that are defined at least have readable names
  • If the app grew any larger than this, one might be wise to migrate functions into a separate module and import it in app.py
• Note the lack of a proper README / we just "presume" the user knows what to do with the presence of a Makefile. Is this acceptable in your opinion?
  • Very minimal Makefile is "sort of self-documenting" but many people don't know to look there. It could use documentation so that make help at least produces some sort of a helpful guide

Usage

(if using local python instead of docker):

make install

then

make run

and visit localhost:8501 (or <tld>/<user>/proxy/8501/ in Jupyter if you have jupyter-server-proxy installed to access the app via proxy)