Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:93692
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: pass (pb1.pair.com: domain gmail.com designates 209.85.213.50 as permitted sender)
MIME-Version: 1.0
In-Reply-To: <295c09d5-01af-1528-8e61-00dc6ee6c69e@fleshgrinder.com>
References: <CAKws9z114YcHkDaXO3o-E0JuHR10WsPzyedeF_8Q=shHDziwug@mail.gmail.com>
	<CADyq6sKr_6qi4Fnk9+yxgCA5j_xF7B7vxq7HH5_nneax5bLf5A@mail.gmail.com>
	<295c09d5-01af-1528-8e61-00dc6ee6c69e@fleshgrinder.com>
Date: Wed, 1 Jun 2016 12:46:02 -0700
Message-ID: <CAFWS2+GKu04ULjm7m65B4U+YgE6KR-T4gJGrpi5wr7c8tr=0NA@mail.gmail.com>
To: internals <internals@lists.php.net>
Cc: Marco Pivetta <ocramius@gmail.com>, Scott Arciszewski <scott@paragonie.com>
Content-Type: text/plain; charset=UTF-8
Subject: Re: [PHP-DEV] [RFC] Libsodium - Discussion
From: ronabop@gmail.com (Ronald Chmara)

On Wed, Jun 1, 2016 at 10:26 AM, Fleshgrinder <php@fleshgrinder.com> wrote:
> On 6/1/2016 12:48 PM, Marco Pivetta wrote:
>> I also agree with Remi on naming: let's avoid calling the extension
>> `libsodium`.
> On 6/1/2016 12:48 PM, Marco Pivetta wrote:
>>  1. is there a particular reason why abbreviations are used? For instance,
>> why `sodium_randombytes_buf()` instead of `sodium_random_bytes_buffer()`?
>>  2. from a naming perspective, I'd expect `sodium_randombytes_buf()` to
>> give me a buffer of random bytes (probably as a stream), but it returns the
>> actual string of random bytes. Again: confusing naming
>>  3. can we avoid using "themed" naming? For example, instead of
>> `sodium_crypto_secretbox()`, it would be best to express what it actually
>> does, like `sodium_encrypt_and_sign()`. While the naming may be emerging
>> from lower layers, I still (like I did with other RFCs) disagree with
>> inheriting confusing naming. This will just cause users to look up the
>> naming up when reading or writing code, and ultimately add up to silly
>> bugs. I can already foresee that people will use the API incorrectly just
>> because of the naming.
> I agree here too but read on.
>
> On 6/1/2016 12:48 PM, Marco Pivetta wrote:
>>  4. can't we just keep it namespaced under `Sodium`, instead of adding more
>> stuff to the root level namespace? Does anyone have a reference to the
>> coding standards that would cause the rename?
>>
> I was the person who brought this up because it is not desired according
> to the existing CODING STANDARD:
>
> https://github.com/php/php-src/blob/master/CODING_STANDARDS

Hi. https://github.com/php/php-src/commit/aa203477bc24b1fadc16d65533c1749162260592
was my commit, put together as a result of discussions on this list
(and sidebars). I can try to speak to it from memory.

> Note that it also encourages this weird C style naming with
> abbreviations, hence, I would be open for discussing it.

It was 2000, 16 years ago.

WRT: "C style naming": C style PHP, *was* a big part of the PHP
adoption base in 2000. No objects. No inheritance. No classes. No
namespaces. Folks were also coming to PHP from ColdFusion, from Perl,
from JavaScript, and bringing their language conventions with them.
Without many guide rails, there was a weird mix of CreaTive_nameing
(and spelling). Conventions like verbnoun, Noun_Verb,
parent_Verb_noun, Parent(Noun())....(and most imaginiable
permutations) were sprinkled throughout the code, throughout
documentation, throughout the community... and one of the earliest
public complaints about PHP was about about inconsitent function
naming. The goal was to bend the curve, over the years, to bring some
order and consistency, not just to internal function naming (as in
this case), but to the entire PHP ecosystem. Thus, the standards about
parent naming, about underscores and....

...Abbreviation: In 2000, most PHP code was typed, manually, No IDE
completion, no built-in syntax checking, no code generators, every
single keystoke was a human hammering away in emacs/vi, BBedit,
Notepad (etc.), and longer function names tended to decrease code
quality (due to increased human error potential), and take up valuable
screen space (800x600 pixels on emergency terminals, though a nice
developer setup could have had 1024x768 pixels on a screen, all *at
the same time*.)  Coding houses still had rules like "maximum of 80
characters per line", to encourage brevity. Abbreviation in this
environment made for more compact code, with less typing errors, but
came with the costs of inconsistent abbreviations, and decreased
readability.

In 2016, using an editor with built in syntax highlighting,
auto-completion, while at coding desks measuring in thousands of
pixels across multiple screens, it seems a bit dated, but when
debugging text files with vi on a spare monochrome terminal session,
late night over a modem at 3,600 Kbps, those things mattered a great
deal. For folks who are still using modems, terminals, and updating
their PHP on 800 pixel screens, I imagine they might still matter.

-Ronabop