new comments and small code re-structure