clarify code/comments and fix typos