add comments and rename some variables

there shouldn't be any change of functionality in here