clarify with more comments, move static method defs