minor code refactoring after awesome first version
improved comments of globally used functions