Junio C Hamano <gitster@xxxxxxxxx> writes: > When we say an option's value is expressed in <percent>, unless we > are careful, people will assume that the valid value the option will > take will lie between 0 and 100, and you cannot blame them. IOW, > while the word "percent" may be 100% correct in your mind, the way > it is used to describe the feature in "git range-diff --help", it > was not sufficient to help readers. Stepping back a bit, I find that saying "--creation-factor=<percent>" is like giving "--max-size=<bytes>". They both make it clear that the readers express the number in what scale, but fails to explain what the number means. It is especially hard for readers when the name of the option does not help explain what the number is, e.g. "max size, size of what?" is a valid question when dealing with "--max-size", and without the question answered, the readers cannot decide what value they want to give to achieve the effect they want. the reader would want to know what it is (e.g. maximum memory that is allowed to be allocated on heap) and how it is measured (i.e. in bytes). The former helps the readers guess what a reasonable value they want to specify is (e.g. "I can afford to dedicate yMB"), and the latter is essential for the readers to decide how exactly they express what they chose (e.g. "I want to give yMB, but it is measured in bytes, so I'll write y * 10^20 here"). We need both. So _after_ they decide that 1.20 is the right number they want to give to --creation-factor, the knowledge that the number is expressed as percent does help them to write --creation-factor=120 correctly (not --creation-factor=1.20). But for readers to come up with the number 1.20, there needs a better explanation of what the number means in the first place. "Go read the algorithm section" is better than having nothing there, but we should be able to do better by having a simple-to-understand single paragraph description. Thanks.
