Open Stack

We've been talking a bit theoretically here. Let me try to jump in
with two use cases.

1. Someone needs to add functionality to a class but can't add it back
upstream. That could be because they are in a hurry to get their app
out and aren't concerned with contributing it or because the
organization they work for won't let them release it in a timely
manner or ever.

2. A vendor needs to extend a class to add functionality. For example,
extending objet storage to add CDN support.

I've personally run into cases in codebases to do both of these. While
I was sitting here I came up with multiple examples of both that I've
experienced and seen.

When I look at this SDK I look at the library in it as a collection of
building blocks that can be swapped out and used together with some
helper code to make it easily work together. One can have access to
all the low level parts and use them or use a high level API and
brings it together.

PHP is a popular language. According to w3techs.com "PHP is used by
82.1% of all the websites whose server-side programming language we
know". The style of extension you're talking about is used by a subset
of PHP developers. Should we enable folks to extend this codebase the
way they generally extend code or push them into extending this in a
different manner from the other code they work with?

You can allow for extension along multiple avenues and still have good
design. A number of popular languages don't have the ability to use
final or private. They have well designed apps and libraries without a
problem.

If we want to have something well designed we should have interfaces.
Anything that implements those interfaces should be fine to use with
anything that accepts them. We provide classes that handle the
interactions with the services. They can be extended, replaced, or
what not. As long as the class implements the interface with the other
things that work with that interface it's fine.

One thing did catch my attention. "we need to understand how and why
users want to interact with, or augment, the functionality of our
SDK". I don't think we'll ever be able to know all the ways people may
want to extend things in the ways they are comfortable extending
things. There is a wide array of things that this can happen. Trying
to know all these things and control them will be difficult for them
to use and us to support.

- Matt

On Tue, Jun 10, 2014 at 4:10 AM, Choi, Sam <sam.choi at hp.com> wrote:
> To be clear, I don’t question his credentials as the blog post was quite
> thorough and informative. I’m just pointing out that he may be writing the
> post primarily from the viewpoint of an enterprise developer.
>
>
>
> About the “nobody else is using it” argument, I guess I should have
> clarified so my apologies. Linking back to my previous statement, I’m saying
> that there are occasionally different design philosophies and opinions based
> on the type of project. It has simply been my observation that the
> enterprise applications I’ve dealt with did use ‘final’ for a number of
> classes. As I mentioned, this makes sense since this is in the scope of a
> closed environment and the author is trying to enforce a constraint of
> future developers who may edit legacy code many years later. So in this
> context, sure, ‘final’ classes can prove to be useful.
>
>
>
> For open source APIs, final classes are used much more sparingly since the
> end goal should really be to allow other devs to make practical applications
> by using the API to suit their needs. Also, ‘better ways’ to allow
> extensions are fairly subjective and based on a dev’s past experience and
> current project. As Matt mentioned, we need to help the typical PHP dev, who
> may naturally gravitate towards extending based on past experience. On the
> other hand, the top devs will find clever workarounds to suit their needs.
> So again, why enforce the end users to follow a specific and opinionated
> design philosophy?
>
>
>
>
>
> From: Jamie Hannaford [mailto:jamie.hannaford at rackspace.com]
> Sent: Tuesday, June 10, 2014 12:44 AM
> To: Matthew Farina; Choi, Sam
> Cc: Glen Campbell; OpenStack Development Mailing List (not for usage
> questions); Shaunak Kashyap; Farina, Matt
> Subject: RE: [openstack-sdk-php] Use of final and private keywords to limit
> extending
>
>
>
> I met Matthias a few weeks ago at PHP day in Verona and he really knows his
> stuff. I don’t think his work experience is relevance - just the clarity and
> applicability of his ideas. FWIW, he works closely with the folks at Inviqa,
> who are creating some of the best OSS in the PHP community. Like me, they
> value his opinion because it’s well-founded and generally applicable to any
> kind of software. Same goes with all the attendees who listen to his talks.
>
>
>
> I don’t understand the “well nobody else is using it” argument. We should
> examine the merits of this proposal based on whether we deem it a good
> design choice, not by looking over our shoulders.
>
>
>
> We are not constricting users here. There are better ways to allow
> extendability that work much better than inheritance
>
>
>
>
>
>
>
> On June 10, 2014 at 9:34:38 AM, Choi, Sam (sam.choi at hp.com) wrote:
>
> Regarding use of the final keyword and limiting extending in general, a few
> thoughts below:
>
> - While I found the blog post about final classes to be informative, I'd
> take it with a grain of salt. The author bills himself as a consultant who
> works with enterprise web applications. Briefly looking at his background,
> practically all his gigs were short consulting jobs. I don't see a track
> record for open source projects so it would appear that his views are likely
> more applicable for enterprise developers working within closed systems.
> - The Java community has already beaten this subject to death over the past
> decade. During recent years, it seems that the debate has waned. I
> occasionally see enterprise Java devs use final to communicate their intent
> so that their system isn't butchered many years down the road when it
> becomes poorly understood legacy code.
> - On the other hand, I hardly ever see final classes in open source
> code/APIs.
> - Regarding future-proofing, I agree that it's easier to switch from final
> to not using final than the other way around. However, I've actually had
> cases where I needed to extend a final class in an API and was simply
> annoyed by the author's desire to control how I use the API. I also
> understood that if the author were to change certain things, my extension
> may have to be refactored. That's a risk I'm certainly willing to take to
> get the job done.
>
> Thanks,
> --
> Sam Choi
> Hewlett-Packard Co.
> HP Cloud Services
> +1 650 316 1652 / Office
>
>
>
> Jamie Hannaford
> Software Developer III - CH
>
> Tel:
>
> +41434303908
>
> Mob:
>
> +41791009767
>
>
>
> -----Original Message-----
> From: Matthew Farina [mailto:matt at mattfarina.com]
> Sent: Monday, June 09, 2014 7:09 AM
> To: Jamie Hannaford
> Cc: Shaunak Kashyap; Glen Campbell; OpenStack Development Mailing List (not
> for usage questions); Choi, Sam; Farina, Matt
> Subject: Re: [openstack-sdk-php] Use of final and private keywords to limit
> extending
>
> If you don't mind I'd like to step back for a moment and talk about the end
> users of this codebase and the types code it will be used in.
>
> We're looking to make application developers successful in PHP. The top 10%
> of PHP application developers aren't an issue. If they have an SDK or not
> they will build amazing things. It's the long tail of app devs. Many of
> these developers don't know things we might take for granted, like
> dependency injection. A lot of them may writing spaghetti procedural code. I
> use these examples because I've run into them in the past couple months. We
> need to make these folks successful in a cost effective and low barrier to
> entry manner.
>
> When I've gotten into the world of closed source PHP (or any other language
> for that matter) and work that's not in the popular space I've seen many
> things that aren't clean or pretty. But, they work.
>
> That means this SDK needs to be useful in the modern frameworks (which vary
> widely on opinions) and in environments we may not like.
>
> The other thing I'd like to talk about is the protected keyword. I use this
> a lot. Using protected means an outside caller can't access the method. Only
> other methods on the class or classes that extend it.
> This is an easy way to have an API and internals.
>
> Private is different. Private means it's part of the class but not there for
> extended classes. It's not just about controlling the public API for callers
> but not letting classes that extend this one have access to the
> functionality.
>
> Given the scope of who our users are...
>
> - Any place we use the `final` scoping we need to explain how to extend it
> properly. It's a teaching moment for someone who might not come to a
> direction on what to do very quickly. Think about the long tail of
> developers and projects, most of which are not open source.
>
> Note, I said I'm not opposed to using final. It's an intentional decision.
> For the kinds of things we're doing I can't see all to many use cases for
> using final. We need to enable users to be successful without controlling
> how they write applications because this is an add-on to help them not a
> driver for their architecture.
>
> - For scoping private and public APIs, `protected` is a better keyword
> unless we are intending on blocking extension. If we block extension we
> should explain how to handled overriding things that are likely to happen in
> real world applications that are not ideally written or architected.
>
> At the end of the day, applications that successfully do what they need to
> do while using OpenStack on the backend is what will make OpenStack more
> successful. We need to help make it easy for the developers, no matter how
> they choose to code, to be successful. I find it useful to focus on end
> users and their practical cases over the theory of how to design something.
>
> Thoughts,
> Matt
>
>
> On Fri, Jun 6, 2014 at 10:01 AM, Jamie Hannaford
> <jamie.hannaford at rackspace.com> wrote:
>> So this is an issue that’s been heavily discussed recently in the PHP
>> community.
>>
>> Based on personal opinion, I heavily favor and use private properties
>> in software I write. I haven’t, however, used the “final” keyword that
>> much.
>> But the more I read about and see it being used, the more inclined I
>> am to use it in projects. Here’s a great overview of why it’s useful
>> for public
>> APIs: http://verraes.net/2014/05/final-classes-in-php/
>>
>> Here’s a tl;dr executive summary:
>>
>> - Open/Closed principle. It’s important to understand that “Open for
>> extension”, does not mean “Open for inheritance”. Composition,
>> strategies, callbacks, plugins, event listeners, … are all valid ways
>> to extend without inheritance. And usually, they are much preferred to
>> inheritance – hence the conventional recommendation in OOP to “favour
>> composition over inheritance”.
>> Inheritance creates more coupling, that can be hard to get rid of, and
>> that can make understanding the code quite tough.
>>
>> - Providing an API is a responsibility: by allowing end-users to
>> access features of our SDK, we need to give certain guarantees of
>> stability or low change frequency. The behavior of classes should be
>> deterministic - i.e. we should be able to trust that a class does a
>> certain thing. There’s no trust whatsoever if that behavior can be edited
>> and overridden from external code.
>>
>> - Future-proofing: the fewer behaviours and extension points we
>> expose, the more freedom we have to change system internals. This is
>> the idea behind encapsulation.
>>
>> You said that we should only use private and final keywords if there’s
>> an overwhelming reason to do so. I completely disagree. I actually
>> want to flip the proposition here: I think we should only use public
>> keywords if we’re CERTAIN we want to encourage and allow the
>> inheritance of that class. By making a class inheritable, you are
>> saying to the outside world: this class is meant to be extended. And the
>> majority of times this is not what we want.
>> Sure there are times when inheritance may well be the best option -
>> but you can support extension points in different, often better, ways.
>> Declaring explicitly what the extension points are is part of the
>> contract your code has with the rest of the system. Final classes help
>> to enforce this contract.
>>
>> To summarize, we have nothing to lose by favoring private and final
>> keywords. We gain the above advantages, and if we later decide to open
>> up that class as an extension point we can remove the keywords without
>> any issues. Should a valid reason come up to open it up, it will be
>> easy to do so, because nothing depends on it being closed. On the
>> other hand, if you start by making everything open or inheritable, it
>> will be very hard to close it later.
>>
>> Jamie
>>
>> On June 5, 2014 at 6:24:52 PM, Matthew Farina (matt at mattfarina.com) wrote:
>>
>> Some recent reviews have started to include the use of the private
>> keyword for methods and talk of using final on classes. I don't think
>> we have consistent agreement on how we should do this.
>>
>> My take is that we should not use private or final unless we can
>> articulate the design decision to intentionally do so.
>>
>> To limit public the public API for a class we can use protected.
>> Moving from protected to private or the use of final should have a
>> good reason.
>>
>> In open source software code is extended in ways we often don't think
>> of up front. Using private and final limits how those things can
>> happen. When we use them we are intentionally limiting extending so we
>> should be able to articulate why we want to put that limitation in
>> place.
>>
>> Given the reviews that have been put forth I think there is a
>> different stance. If there is one please share it.
>>
>> - Matt
>>
>>
>>
>> Jamie Hannaford
>> Software Developer III - CH
>> Tel: +41434303908
>> Mob: +41791009767
>>
>>
>>
>> Rackspace International GmbH a company registered in the Canton of
>> Zurich, Switzerland (company identification number CH-020.4.047.077-1)
>> whose registered office is at Pfingstweidstrasse 60, 8005 Zurich,
>> Switzerland.
>> Rackspace International GmbH privacy policy can be viewed at
>> www.rackspace.co.uk/legal/swiss-privacy-policy
>> -
>> Rackspace Hosting Australia PTY LTD a company registered in the state
>> of Victoria, Australia (company registered number ACN 153 275 524)
>> whose registered office is at Suite 3, Level 7, 210 George Street,
>> Sydney, NSW 2000, Australia. Rackspace Hosting Australia PTY LTD
>> privacy policy can be viewed at
>> www.rackspace.com.au/company/legal-privacy-statement.php
>> -
>> Rackspace US, Inc, 5000 Walzem Road, San Antonio, Texas 78218, United
>> States of America Rackspace US, Inc privacy policy can be viewed at
>> www.rackspace.com/information/legal/privacystatement
>> -
>> Rackspace Limited is a company registered in England & Wales (company
>> registered number 03897010) whose registered office is at 5 Millington
>> Road, Hyde Park Hayes, Middlesex UB3 4AZ.
>> Rackspace Limited privacy policy can be viewed at
>> www.rackspace.co.uk/legal/privacy-policy
>> -
>> Rackspace Benelux B.V. is a company registered in the Netherlands
>> (company KvK nummer 34276327) whose registered office is at
>> Teleportboulevard 110,
>> 1043 EJ Amsterdam.
>> Rackspace Benelux B.V privacy policy can be viewed at
>> www.rackspace.nl/juridisch/privacy-policy
>> -
>> Rackspace Asia Limited is a company registered in Hong Kong (Company no:
>> 1211294) whose registered office is at 9/F, Cambridge House, Taikoo
>> Place,
>> 979 King's Road, Quarry Bay, Hong Kong.
>> Rackspace Asia Limited privacy policy can be viewed at
>> www.rackspace.com.hk/company/legal-privacy-statement.php
>> -
>> This e-mail message (including any attachments or embedded documents)
>> is intended for the exclusive and confidential use of the individual
>> or entity to which this message is addressed, and unless otherwise
>> expressly indicated, is confidential and privileged information of
>> Rackspace. Any dissemination, distribution or copying of the enclosed
>> material is prohibited. If you receive this transmission in error,
>> please notify us immediately by e-mail at abuse at rackspace.com and
>> delete the original message. Your cooperation is appreciated.
>
> Rackspace International GmbH a company registered in the Canton of Zurich,
> Switzerland (company identification number CH-020.4.047.077-1) whose
> registered office is at Pfingstweidstrasse 60, 8005 Zurich, Switzerland.
> Rackspace International GmbH privacy policy can be viewed at
> www.rackspace.co.uk/legal/swiss-privacy-policy
> -
> Rackspace Hosting Australia PTY LTD a company registered in the state of
> Victoria, Australia (company registered number ACN 153 275 524) whose
> registered office is at Suite 3, Level 7, 210 George Street, Sydney, NSW
> 2000, Australia. Rackspace Hosting Australia PTY LTD privacy policy can be
> viewed at www.rackspace.com.au/company/legal-privacy-statement.php
> -
> Rackspace US, Inc, 5000 Walzem Road, San Antonio, Texas 78218, United States
> of America
> Rackspace US, Inc privacy policy can be viewed at
> www.rackspace.com/information/legal/privacystatement
> -
> Rackspace Limited is a company registered in England & Wales (company
> registered number 03897010) whose registered office is at 5 Millington Road,
> Hyde Park Hayes, Middlesex UB3 4AZ.
> Rackspace Limited privacy policy can be viewed at
> www.rackspace.co.uk/legal/privacy-policy
> -
> Rackspace Benelux B.V. is a company registered in the Netherlands (company
> KvK nummer 34276327) whose registered office is at Teleportboulevard 110,
> 1043 EJ Amsterdam.
> Rackspace Benelux B.V privacy policy can be viewed at
> www.rackspace.nl/juridisch/privacy-policy
> -
> Rackspace Asia Limited is a company registered in Hong Kong (Company no:
> 1211294) whose registered office is at 9/F, Cambridge House, Taikoo Place,
> 979 King's Road, Quarry Bay, Hong Kong.
> Rackspace Asia Limited privacy policy can be viewed at
> www.rackspace.com.hk/company/legal-privacy-statement.php
> -
> This e-mail message (including any attachments or embedded documents) is
> intended for the exclusive and confidential use of the individual or entity
> to which this message is addressed, and unless otherwise expressly
> indicated, is confidential and privileged information of Rackspace. Any
> dissemination, distribution or copying of the enclosed material is
> prohibited. If you receive this transmission in error, please notify us
> immediately by e-mail at abuse at rackspace.com and delete the original
> message. Your cooperation is appreciated.