On Monday, 10 June 2013 at 07:13:49 UTC, Jacob Carlborg wrote:
> On 2013-06-10 04:33, Andrei Alexandrescu wrote:
>
>> Guys, they're function local vars. A comment would suffice.
>
> That doesn't mean the names should be less understandable. We're writing open source here. I think most names should be named as if they were part of the public API.

I object to your use of the name "API". Please use the more understandable "Application Programming Interface" in future.

:-)

/joke

The point is that there is value in terseness. That's what abbreviations are for. If you are to refer to Application Programming Interface multiple times then it can make text more understandable to abbreviate it (as you have). Reducing the size of identifiers allows the reader to more clearly see the meaning of the text. The same is true in code.

Compare:

solution = (-firstCoefficient + squareRoot(secondCoefficient * secondCoefficient - 4 * firstCoefficient * thirdCoefficient) / (2 * firstCoefficient);

to

// a, b, c - coefficients
// x - solution
x = (-b + sqrt(b*b - 4*a*c)) / (2 * a);

On 2013-06-10 09:35, Walter Bright wrote:

> There's no way to put the "why" in code.

That's why I said "Most times" and not "always". As with everything, there are exceptions.

-- 
/Jacob Carlborg

On 2013-06-10 09:57, Peter Alexander wrote:

> I object to your use of the name "API". Please use the more
> understandable "Application Programming Interface" in future.
>
> :-)
>
> /joke

Some are abbreviations are commonly know. In the programming world API is one of them. FTP and HTTP are other examples. I would say that "di" and "si" are not.

> The point is that there is value in terseness. That's what abbreviations
> are for. If you are to refer to Application Programming Interface
> multiple times then it can make text more understandable to abbreviate
> it (as you have). Reducing the size of identifiers allows the reader to
> more clearly see the meaning of the text. The same is true in code.
>
> Compare:
>
> solution = (-firstCoefficient + squareRoot(secondCoefficient *
> secondCoefficient - 4 * firstCoefficient * thirdCoefficient) / (2 *
> firstCoefficient);
>
> to
>
> // a, b, c - coefficients
> // x - solution
> x = (-b + sqrt(b*b - 4*a*c)) / (2 * a);

If that code is in its own function, I would say it's ok. If that piece of code is mixed in a function with over 500 lines of code and the variables are declared at the top, I would say it's very bad style.

-- 
/Jacob Carlborg

On 6/10/13 3:13 AM, Jacob Carlborg wrote:
> On 2013-06-10 04:33, Andrei Alexandrescu wrote:
>
>> Guys, they're function local vars. A comment would suffice.
>
> That doesn't mean the names should be less understandable. We're writing
> open source here. I think most names should be named as if they were
> part of the public API.

That's an exaggeration. There are plenty of obscure details that help implementers but would be unnecessary to publish with the API.

> It also depends on in what context they are used. Example, in DMD there
> are a lot of functions containing probably more the 500 lines of code
> with variable names with only one letter, declared at the top of the
> function. If you instead have a function with only five or ten lines of
> code it could be ok:
>
> private void foo (ProductInformation pi) { // five lines of code }
>
> I would think the above would be ok. But it should definitely not be
> used in documentation/examples as I see it is now.
>
> BTW, I hate using comments for that. Comments should basically only be
> used for writing API documentation. Most times, if you want to add a
> comment your code is probably not clear enough.

A lot of scientific code would be worse off if it used long variable names. Oftentimes it uses "tau" or "gamma" or even "a" or "k" with an explanatory comment at the top.


Andrei