cvs: peardoc /en/chapters rfcs-entities.xml /en/chapters/rfcs protected-members.xml

cweiske		Sun May  3 17:44:52 2009 UTC

  Added files:                 
    /peardoc/en/chapters/rfcs	protected-members.xml 

  Modified files:              
    /peardoc/en/chapters	rfcs-entities.xml 
  Log:
  And another RFC in the manual: protected members (bug #11198)
  
  
http://cvs.php.net/viewvc.cgi/peardoc/en/chapters/rfcs-entities.xml?r1=1.4&r2=1.5&diff_format=u
Index: peardoc/en/chapters/rfcs-entities.xml
diff -u peardoc/en/chapters/rfcs-entities.xml:1.4 peardoc/en/chapters/rfcs-entities.xml:1.5
--- peardoc/en/chapters/rfcs-entities.xml:1.4	Sun May  3 17:24:31 2009
+++ peardoc/en/chapters/rfcs-entities.xml	Sun May  3 17:44:51 2009
@@ -1,4 +1,5 @@
 &chapters.rfcs.error-handling;
 &chapters.rfcs.header-comments;
+&chapters.rfcs.protected-members;
 &chapters.rfcs.qa-team;
 &chapters.rfcs.version-naming;

http://cvs.php.net/viewvc.cgi/peardoc/en/chapters/rfcs/protected-members.xml?view=markup&rev=1.1
Index: peardoc/en/chapters/rfcs/protected-members.xml
+++ peardoc/en/chapters/rfcs/protected-members.xml
<?xml version="1.0" encoding="UTF-8"?>
<chapter version="5.0" xml:id="chapters.rfcs.protected-members"
         xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
>
  <info>
    <title>Protected Members</title>

    <date>2004-07-03</date>
  </info>

  <para>
   This RFC has been voted on in PEPr as
   <link xlink:href="&url.pear.pepr.proposal;99">proposal #99</link>.
  </para>

  <section xml:id="chapters.rfcs.protected-members.preface">
    <title>Preface</title>

    <para>This RFC aims to resolve whether or not protected class members will
    be prefixed with an underscore, or prefixed with nothing.</para>

    <para>Once a decision has been reached, the result will be added to the
    PEAR coding standards.</para>

    <para>Private members will still be prefixed.</para>

    <note>
      <para>These standards will only apply to PHP5 classes. In PHP4, if it's
      not public it's private and thus prefixed.</para>
    </note>
  </section>

  <section xml:id="chapters.rfcs.protected-members.voting">
    <title>Voting</title>

    <note>
      <para>The voting resulted in <link
      xlink:href="http://pear.php.net/pepr/pepr-votes-show.php?id=99">a sum of
      +27 votes</link>. Thus, the "no prefix" solution had been chosen.</para>
    </note>

    <para>A vote of 0 will not be counted.</para>

    <para>If the overall score at the end of the call-for-votes is positive,
    class members will not be prefixed. If negative, they will be
    prefixed.</para>

    <section xml:id="chapters.rfcs.protected-members.voting.noprefix">
      <title>No prefix (accepted)</title>

      <para>A vote of <literal>+1</literal> suggests class members should not
      be prefixed.</para>

      <programlisting role="php">class Foo
{
    protected $somevar;
    protected function somefunc();
}</programlisting>
    </section>

    <section xml:id="chapters.rfcs.protected-members.voting.prefix">
      <title>Prefix (not accepted)</title>

      <para>A vote of <literal>-1</literal> suggests class members should be
      prefixed with an underscore.</para>

      <programlisting role="php">class Foo
{
    protected $_somevar;
    protected function _somefunc();
}</programlisting>
    </section>
  </section>

  <section xml:id="chapters.rfcs.protected-members.info">
    <title>Information</title>

    <section xml:id="chapters.rfcs.protected-members.info.changes">
      <title>What's changed?</title>

      <para>PHP5 Introduces PPP - Private, Public and Protected.</para>
    </section>

    <section xml:id="chapters.rfcs.protected-members.info.protpriv">
      <title>What's protected and private?</title>

      <para>Protected members can be accessed in classes extending the class
      they are declared in, where as private members can only be accessed by
      the class they belong to.</para>
    </section>

    <section xml:id="chapters.rfcs.protected-members.info.previously">
      <title>What did we use to do, and why?</title>

      <para>In PHP4, both private and protected members were prefixed with an
      underscore. This was to ensure the user of the class knew what methods
      were available to them, and not to mess with anything else.</para>

      <para>One of the key reasons for prefixed members is the visual
      expression of "Do not mess with this member, I may remove/rename it in
      the future". This is fine for private members, however will not follow
      for protected members when the class is extended by the user.</para>
    </section>

    <section xml:id="chapters.rfcs.protected-members.info.ignore">
      <title>Is it possible to accidently ignore the declarations?</title>

      <para>If a member is declared as protected (using the protected
      keyword), an E_FATAL error will be thrown if the member is used
      incorrectly.</para>

      <para>PHP5 will also provide errors if a user attempts to redeclare a
      protected var as private. However protected members may be declared
      public by child classes.</para>

      <para>In this regard 'protected' is like public in terms of the
      obligations of the library author. For example, if you want to keep your
      public API small, but allow extending classes to expose more
      functionality. Or, if you would prefer to access class properties
      directly rather than using setter methods, you can redeclare the
      properties public in a child class.</para>

      <para>In these situations, public vars would be prefixed as
      "private".</para>
    </section>

    <section xml:id="chapters.rfcs.protected-members.info.readability">
      <title>Does prefixing enhance readability?</title>

      <para>Some would argue yes, some would argue no. Most large classes
      consist almost completely of protected members, with the public members
      reserved for the API. In this situation, does having almost everything
      underscored really enhance readability?</para>

      <para>Is private the same as protected? No, definitly not. Then why
      should it be prefixed the same? Some argue this actually decreases
      readability and confuses private members.</para>

      <para>Is protected the same as public? No, definitly not. The user can't
      use a protected member (unless they are extending the class). In this
      example, protected has a lot more in common private. Should the user be
      protected visually (as well as with the language construct) from using
      protected members?</para>
    </section>
  </section>
</chapter>