reorder methods, refactor complicated conditions into helper methods, add more descriptive docstrings and add sample queries in majority of the code flow branches to easier navigate the code

Author: collerek