Documentation: One Letter Variables

[jeffmarshall]

Can we please not use one-letter variables in example code? Call me old-fashioned, but In My Day we either left comments that explained our code, or we used meaningful, accurate variable names. This example code in the README has neither:

Wouldn't it be better if somebody could glance at this code and have some idea what's going on?

[anton-roos]

I don't understand, i is conventionally used as an iterator wirh j and k.

e is an element.
s is a slice.

Not sure where the confusion are? I was able to deduce from reading the code very easily.

[kuredoro]

But this is a bad practice, isn't it? If you need to deduce what the variables mean from the code to understand it, then it's a poorly readable code. At least naming those things as item instead of e, lessThanPivotCount instead of i, and pivotLastArray instead of s.

See? A programmer can just put e i j k s e everywhere without understanding what they write, but to come up with readable names, you need to understand what the code does. And not only for the writer it unloads a bunch of mental burden, but for the readers too (so much that now they can pinpoint why the code is wrong on code reviews). That's why descriptive names are so important...

[Taack]

Somehow I prefer short variable names for readability in local scope. I prefer reading i than lessThanPivotCount (whatever it is supposed to tell).

Adding code semantics into variable names is kind of redundant information to my mind, for local scopes.

[geoffromer]

I agree. e, p, and s probably violate our project's C++ style guide (but T and i are OK because they have very well-known conventional meanings), and I don't see any reason for Carbon style to be different in this respect. Could you send a PR to fix this, or file an issue?

[jonmeow]

Note, the front page examples are brief in order to fit on the page. This is a trade-off of long variable names and being able to fit in very few columns.