readme and code clarification (part II)