Add sections on use of abbreviations

[jmiller-pwi]

Added documentation for the use of excessive and ambiguous abbreviations. This is something I struggle with as a manager with my team.

@zakirullin Personally, I would be fine dropping the Ambiguous abbreviations section if you feel it isn't that helpful.

[zakirullin]

Hi there! Thanks for your contribution!

Hm, let me think for some time.

It seems for me it's been a while since I saw abbreviations in the code. The statements that you describe are true, but I believe nowadays it is somewhat generally learned and accepted.

Do you face this thing often?

[Bouncner]

For people coming from C, it’s still a thing. Most other languages learned their lesson. 😀

[jmiller-pwi]

Do you face this thing often?

I find that my developers tend to still use abbreviations regularly. I haven't looked at much real-use code outside of our organization, so I can't speak for the "general audience".

But as mentioned, I do see it frequently with my developers. Most often, it's in the form of 1-2 abbreviations in a lambda function. Obviously I'm working with them to curb this, but figured that this could be helpful to the community as a whole. The example given is an extreme, exaggerated to prove a point, but not as far-fetched as some may think.

The section about ambiguous abbreviations is less pertinent, as those are often easy to decode in context, and there usually aren't many of them grouped together.

[jmiller-pwi]

For people coming from C, it’s still a thing. Most other languages learned their lesson.

For context, we're mostly working in TypeScript and Dart (Flutter).

[zakirullin]

@Bouncner @jmiller-pwi

For people coming from C, it’s still a thing. Most other languages learned their lesson. 😀

For context, we're mostly working in TypeScript and Dart (Flutter).

That's interesting. I haven't seen C/TS code with abbreviations for ages, even though I read it every now and then. Sometimes devs introduce a few abbreviated domain concepts, but apart from that the names are quite long. And it is certainly not "a", "b" or "c".

[zakirullin]

https://github.com/php/php-src/blob/master/main/strlcat.c#L66-L67

Certainly, there are things like this. But in this case short variable names seem to be fine, because their scope is very limited and their purpose is very clear. Same goes for "i" in loops.

For global scope variables and module interface abbreviations aren't ok, but this seems to be acknowledged across the industry.