fixup the header with more comments and better organization