Interface & trait naming convention

[Marko Vodanović]

Hi.

I was wandering about naming my interfaces & traits. You guys made an impressive thing with your FIG movement and there's no way I'm writing new code which doesn't comply with PSRs because I believe it is the only PHP future. But at the same time I do want to differentiate interfaces and traits from classes. Since Classes use StudlyCaps for naming, I wanted to prefix my interfaces with lowercase "i" and traits with lowercase "t", so if I had a "Name", an "iName" and a "tName", I would instantly know what it is.

So my question to you is, does this comply with all PSRs? If not (I assume not), would you consider my suggestion for a future PSR.

The alternative is to suffix interfaces and traits with "Interface" and "Trait", but having "NameInterface" and "NameTrait" is really long and ugly to me and if I shorten it to "NameI" and "NameT" (or "IName" and "TName") there's no guarantee that some class won't have these names (although they shouldn't according to good coding practice).

[Phil Sturgeon]

PSR-1 definitely says:

Class names MUST be declared in StudlyCaps.

Sorry, you'll have to go with the suffix approach. 

[Donald Gilbert]

For the Joomla Framework, we opted for the suffix approach. It was cumbersome to begin with, but easy to get used to. It's a commonly accepted practice.

Symfony\HttpKernel\HttpKernelInterface

Joomla\DI\ServiceProviderInterface

When dealing with abstract classes, we prefix with Abstract. So: 

Joomla\Application\AbstractWebApplication

Of course, you're free to do what  you want, but prefixing with a lowercase i or t isn't PSR compatible.

[Chuck Burgess]

Also note the bylaw for naming things that FIG adopted for its own use -- https://github.com/php-fig/fig-standards/blob/master/bylaws/002-psr-naming-conventions.md

CRB
about.me/ashnazg

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/4d6608e9-f5f3-4251-bfa0-f1f343cde3d0%40googlegroups.com.

For more options, visit https://groups.google.com/groups/opt_out.

[Larry Garfield]

Drupal does the same suffixing. I don't particularly like it, but it
works and I've seen it a lot elsewhere. Symfony does that as well.

It would be nice if all interfaces were -able, but in practice a
majority either don't or don't easily. Oh well.

--Larry Garfield

[Levi Morrison]

On Wednesday, January 8, 2014 3:34:08 PM UTC-7, Chuck Burgess wrote:

Also note the bylaw for naming things that FIG adopted for its own use -- https://github.com/php-fig/fig-standards/blob/master/bylaws/002-psr-naming-conventions.md

CRB

Points 1-3 should be overturned in my opinion, *especially from this group!* The fact is that PSRs from this group are for operability and are therefore interfaces by very nature. They reside in a Psr\ namespace which means that you don't need Interface in the name to avoid conflicts, either. It makes for longer names and makes for more cumbersome communication. See: https://github.com/php-fig/fig-standards/pull/244/files#r8744476 and related conversation.

[Phil Sturgeon]

We are not the first group in the world to suggest that naming an interface differently to a class is a good idea. 

[Levi Morrison]

Nor am I the first to suggest that it's actually harmful; what's your point? 

[Phil Sturgeon]

My point is that this is by no means a new conversation being had, and that each side of the fence have their own reasons for doing it. It's basically tabs v spaces, and nobody is ever going to win. 

Changing our naming conventions would mean we need to change PSR-3 and break everything, or leave PSR-3 as it is and have a new naming convention going forwards, which sounds a lot like why strlen() and str_replace() exist. 

Let's not do that. Let's just stick with the naming convention that we have, because personal preference is not all that relevant.

[Mathias Verraes]

This is not like tabs vs spaces. This is about a fundamental interpretation of the raison d'être of interfaces. Needless to say I am with Levi on this.

If I write  something like 

public function doThing(Request $request)

I am not  interested in: 

- who provided $request

- whether Request is an interface or a class or a yet to be invented concept

- how it is implemented

The only thing my client code in interested in, is the roles it provides, aka the functionality it provides, aka the contract it exposes. 

Calling it RequestInterface, implies that you are interested in the fact that it is an interface. What you are getting to from the caller, is not an interface. It is an object that is implemented in a way that is guaranteed to adhere to the contract that the interface happens to describe. 

[Mike van Riel]

Mathias,

I understand it is your personal opinion that suffixing the name of an interface with the word interface provides you with some fundamental understanding of the reason why interfaces exist. I disagree with that statement.

The discussion regarding the name of an class, interface, trait or other structural element is the same as any other coding standards discussion; it comes down to personal preference.

Let's take your example:

> public function doThing(Request $request)

I consider the list of arguments to be a specification of the contract between my calling code and the function/method definition. As such I am
interested in the details of this contract. Does it require a specific class, or its subclass, or can I expect a multitude of classes that implement
a specific set of conditions.

Regarding your other points:

> who provided $request
> how it is implemented

I fail to see how that is related to the name of an interface, especially the latter.

I have several reasons for keeping the current conventions:

1. I do not see what the added value is of changing (satisfying some people's feeling of proper naming will not add intrinsic value)
2. It takes effort, including this discussion, that detracts from activities that add value.
3. The rules of the current bylaw represent a significant portion of the member projects' naming scheme and is thus familiair.

I also would like to address Levi's argument:

> he fact is that PSRs from this group are for operability and are therefore interfaces by very nature

This is only true for published interfaces; sample code often contains more types of elements including, but not limited to, classes and traits.

Let's put this argument to rest, shall we?

Kind regards,

Mike

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/848e1f68-9997-40b3-b305-a9b3e5cd0e2f%40googlegroups.com.

[Mathias Verraes]

Hey Mike, 

I agree that this is not the place for this. :-)

I will refrain from discussing it here any further, but I'd be happy to continue anywhere else. 

Mathias

--
You received this message because you are subscribed to a topic in the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/php-fig/10lM-UNudvU/unsubscribe.
To unsubscribe from this group and all its topics, send an email to php-fig+u...@googlegroups.com.

To post to this group, send email to php...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/52CE44EE.40704%40gmail.com.

For more options, visit https://groups.google.com/groups/opt_out.

--

Mathias Verraes

mat...@verraes.net

http://verraes.net

@mathiasverraes

[William DURAND]

IMO, either you will suffix interfaces or implementations (à la Java) anyway, because, at some point, you need to separate them:

* RequestImpl implements Request

* Request implements RequestInterface

But the real issue is that we are bad at naming interfaces, so we end up by suffixing them. As an interface describes a contract, its name should reflect such a contract rather than being a GenericNameInterface.

My 2 cents,

William

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/52CE44EE.40704%40gmail.com.

[Marko Vodanović]

Yes, that's why I wanted this to be considered for a new PSR, and it needn't be a MUST, MAY is enough.

For example, if you have a file called UserInterface.php. Can you tell from the name alone does it contain a PHP interface with some common methods for different user classes (like for CMS users and frontend users) or does it contain a class which implements some kind of a user interface (GUI or something)? If the small-caps prefix were to be allowed, it would be obvious that the file iUser.php contains the first, and UserInterface.php the second.

[Sebastian Krebs]

2014/1/9 Marko Vodanović <morg...@gmail.com>

On Wednesday, January 8, 2014 10:08:48 PM UTC+1, Phil Sturgeon wrote:

PSR-1 definitely says:

Class names MUST be declared in StudlyCaps.

Sorry, you'll have to go with the suffix approach. 

Yes, that's why I wanted this to be considered for a new PSR, and it needn't be a MUST, MAY is enough.

I don't think it's a good idea: Having to libraries, that both claims to be "PSR-foo-compatible", but in one "Request" is a class and in the other it is an interface it is even more confusing.

I have written libraries, in which I havent used any suffix, or prefix, or whatever. But I've also written libraries _with_ suffix. Both worked perfectly fine. It _is_ like "tab-vs.-spaces". Loosen this constraint in a single PSR would mean to sacrifice the expressiveness: Saying "Do whatever you want" is a bad recommendation (or not recommendation at all, but a nice story :D).

 

For example, if you have a file called UserInterface.php. Can you tell from the name alone does it contain a PHP interface with some common methods for different user classes (like for CMS users and frontend users) or does it contain a class which implements some kind of a user interface (GUI or something)?

Sounds like edge-cases to me, that shouldn't affect the common cases. It's easier to name the interface-implementation differently.

 

If the small-caps prefix were to be allowed, it would be obvious that the file iUser.php contains the first, and UserInterface.php the second.

My 2 cent: Having a huge bunch of files all starting with one of "c", "i", or "t" is ugly and decrease clarity. I can argue about the "ugly", but for example in Yii I find it quite hard to find, what I am looking for, because you cannot rely on the first character anymore. Everything looks "mixed up".

 

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/571d38fd-e368-4f68-861d-ff43b3f51e7b%40googlegroups.com.

For more options, visit https://groups.google.com/groups/opt_out.

--
github.com/KingCrunch

[Moisa Teodor]

For interfaces, whenever I can, I usually use a suffix like 'able' or 'Aware', so that the interface name is an adjective. Some examples:

 - Writable, Readable (also PHP's Serializable, Countable, Traversable)

 - ConnectionAware, ContextAware etc.

I use this convention because PHP is not the only language I write in, so I tend to use the same style/conventions whenever I can, even across languages.

Now, on the other hand, this group has a bylaw which enforces the use of the 'Interface' suffix for interfaces, the 'Trait' suffix for traits and the 'Abstract' prefix for abstract classes on any code this group releases. This by itself is not a bad choice at all, as it serves the purpose of being extremely clear and consistent when code produces by this group is used in different projects. It is something deserving a big applause, as it is proof that projects can work together nicely, even in the PHP community.

But again, it is a matter of choice. Neither PSR-1 nor PSR-2 are enforcing you to a specific naming convention for differentiating Interfaces, Traits, Abstract classes and regular Classes among themselves.

Hope this helps.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/FDC2A9B8-6557-43A2-A785-4C58E856FF23%40gmail.com.

For more options, visit https://groups.google.com/groups/opt_out.

--
Doru Moisa
web: http;//moisadoru.wordpress.com
tel: +40 720 861 922
Bucharest, Romania

[Donald Gilbert]

And what about PHP's ArrayAccess, IteratorAggregate, SeekableIterator or SplObserver interfaces. None of those (and there are others) are suffixed with "-able".  Like everything in PHP, it's completely inconsistent.

We've already decided in our bylaws on how our code will be named, let's not revisit it. It's down to personal preference on how you want to do it in your code, and changing the bylaw now to fit one persons current preference is sure to conflict with someone else's preference on this matter in 6 months. It's just not worth the time.

[Moisa Teodor]

Hi Donald,

Marko asked how should he write his code in order to be PSR compatible. As far as I know, there is no PSR that enforces this, other than the aforementioned bylaw, which IMHO is just fine. If there are people who want it changed, they should open a separate thread for that.

Also, about the mention of ArrayAccess, IterratorAggregate ... what is your point exactly ? I mentioned Comparable and Traversable as examples of adjective interface names. I did not say all the PHP interfaces are like that :). Unfortunately, we all know that PHP's API is extremely inconsistent, when compared to other languages APIs, like Java's, nothing new here.

As a bottom line, my current understanding is that there is no PSR that enforces a specific naming convention for interfaces, traits or abstract classes for code that is not official PHP-FIG released code (for which, there is a bylaw). 

Please correct me if I'm wrong.

--

You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/4ebed995-dbc8-4a8a-816e-0244f22eb5ba%40googlegroups.com.

For more options, visit https://groups.google.com/groups/opt_out.

[Phil Sturgeon]

Right, Marko asked a simple question and got a simple answer, then this was "hijacked" by folks injecting their personal preference into the discussion. 

There is no PSR for specific naming of interfaces, traits, etc, but PSR-1 definitely says StudlyCaps, so do that and you're golden. WE use a naming convention, and should continue to use that naming convention. PHP itself has a different naming convention each day of the week, which we won't be copying. FooInterface, BarTrait, is in the bylaw and we should absolutely stick to that.

:)

[Donald Gilbert]

My points, as clearly stated in my email:

1) inconsistencies abound even within the core language, do don't worry about it too much.

2) it's all down to personal preference.

3) the FIG already decided how we are going to do our code, and you can follow it if you want to, but you don't have to.

You are right in that there is no specific PSR that determines naming, but PSR-1 says that you must use StudlyCaps for names of classes, interfaces and traits. This means that iUser is not valid PSR-1. It's up to you how to apply it beyond that.

[Drak]

On 9 January 2014 18:16, Phil Sturgeon <em...@philsturgeon.co.uk> wrote:

Right, Marko asked a simple question and got a simple answer, then this was "hijacked" by folks injecting their personal preference into the discussion. 

There is no PSR for specific naming of interfaces, traits, etc, but PSR-1 definitely says StudlyCaps, so do that and you're golden. WE use a naming convention, and should continue to use that naming convention. PHP itself has a different naming convention each day of the week, which we won't be copying. FooInterface, BarTrait, is in the bylaw and we should absolutely stick to that.

Well said: now can this thread please die already? 

Drak

[Levi Morrison]

We've already decided in our bylaws on how our code will be named, let's not revisit it. 

This deeply bothers me; you are essentially saying that the first time around you got a perfect solution. As someone who writes software as a living, you know full well this is not true. So why then are we not revisiting it? Besides, who is in the group changes over time so new members didn't necessarily agree to the by-law anyway - who is to say they don't have a powerful insight that nobody who came before had?

[Donald Gilbert]

Because it's a naming convention, and it literally doesn't matter. There is no "right" or "wrong" way to do it. However, if we change the bylaw to follow someone's personal preference today, then we have to update all existing Example and PSR code. Then, when a new preference comes in says that we should be doing iCraZyCAps for interfaces and tBSCAps for traits, and we accept it, we have to go in _again_ and change all existing Example and PSR code.

It's not worth revisiting. I mean c'mon, we have members to vote in and stuff.

[Moisa Teodor]

Yes, this thread will certainly die, but it does not hurt to give some some advices to questions like Marko's. Being expeditive will most likely do a great disservice to this group, and to the overall PHP community. Is it too much to ask for PSR members to be more understanding wit

--

You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/d3122219-11a3-475a-9c2d-a02b4b85f147%40googlegroups.com.

For more options, visit https://groups.google.com/groups/opt_out.

[Moisa Teodor]

Yes, this thread will certainly die, but it does not hurt to give some some advices to questions like Marko's. Being expeditive will most likely do a great disservice to this group, and to the overall PHP community. Is it too much to ask for PSR members to be more understanding with people that are not PSR gurus? Did our hearts got frozen that deep already ?

[Mike van Riel]

Hi Moisa,

As far as I can see Marco his question was answered in the first two replies before the thread was hijacked.

If you believe information is missing, can you indicate what questions are still left unanswered in your opinion?

With kind regards,

Mike van Riel

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/CAEJbJphL-sBCStUAwQCWr%2B0dec0gobg0YJm_7rhtmP8mJ6Fw6w%40mail.gmail.com.

[Moisa Teodor]

Hi Mike,

Yes, you are right - Marko's question was answered, there is no point in continuing this thread. 

Sorry for contributing noise in this thread and group, I will refrain myself from ever posting, unless absolutely necessary. 

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/CAE%3De0zdt8o81MSdPSTDknXCDbWbg-dCsEzo14uATUKVa18i81Q%40mail.gmail.com.

For more options, visit https://groups.google.com/groups/opt_out.

[Mike van Riel]

On 01/10/2014 11:55 AM, Moisa Teodor wrote:
>
> Sorry for contributing noise in this thread and group, I will refrain
> myself from ever posting, unless absolutely necessary.
>

Hello Moisa,

To be honest, I do not understand why you intend to refrain from
posting? Asking for clarification should not be an issue, and I
(attempted to) politely inform you that the question was indeed answered.

If anything I would kindly ask you to consider the impact of your words
and ask before judging us, because of the following sentence:

> Is it too much to ask for PSR members to be more understanding with
people that are not PSR gurus? Did our hearts got frozen that deep already?

I, and I assume other members of PHP-FIG, are happy to answer any
questions related to PSRs and often other topics. If people experience a
certain impatience in our answers that could be because that specific
question has been asked before or because the sender insists on their
opinion and has trouble accepting that some things won't be changed, or
even discussed, as that takes away time and effort that could have been
spent on ironing out PSR drafts or discussing new PSRs.

So my advice to you would be, keep asking your questions and providing
your feedback while offering respect in your words.

[Moisa Teodor]

Hi Mike, all,

It was not my intention to be disrespectful, and I apologize if any of you perceived it this way. I'm not a native english speaker, and sometimes I fail to chose the right wording. I respect you guys and the stuff you do here, as it's one of the best things that ever happened to the PHP community.

Now, when I said that I will refrain from posting unless necessary, I meant that I will not contribute to the noise in these threads, unless I have something really important to say. I noticed that some people complain about too much noise and discussions taking place, and tend to be expeditive and try to kill long threads, so this is merely a reaction to that.

Thanks!

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.

To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+unsubscribe@googlegroups.com.

To post to this group, send email to php...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/52CFD4E1.1000605%40gmail.com.

For more options, visit https://groups.google.com/groups/opt_out.