some bulletproofing and updated comments