improve comments and extract a common function