cvs: peardoc /en/chapters rfcs-entities.xml rfcs.xml /en/chapters/rfcs cs-enhancements.xml /entities global.ent

http://cvs.php.net/viewvc.cgi/peardoc/en/chapters/rfcs-entities.xml?r1=1.8&r2=1.9&diff_format=u
Index: peardoc/en/chapters/rfcs-entities.xml
diff -u peardoc/en/chapters/rfcs-entities.xml:1.8 peardoc/en/chapters/rfcs-entities.xml:1.9
--- peardoc/en/chapters/rfcs-entities.xml:1.8	Mon May  4 18:35:49 2009
+++ peardoc/en/chapters/rfcs-entities.xml	Mon May  4 19:41:43 2009
@@ -1,3 +1,4 @@
+&chapters.rfcs.cs-enhancements;
 &chapters.rfcs.error-handling;
 &chapters.rfcs.estrict-compatibility;
 &chapters.rfcs.header-comments;
http://cvs.php.net/viewvc.cgi/peardoc/en/chapters/rfcs.xml?r1=1.2&r2=1.3&diff_format=u
Index: peardoc/en/chapters/rfcs.xml
diff -u peardoc/en/chapters/rfcs.xml:1.2 peardoc/en/chapters/rfcs.xml:1.3
--- peardoc/en/chapters/rfcs.xml:1.2	Sun May  3 17:24:31 2009
+++ peardoc/en/chapters/rfcs.xml	Mon May  4 19:41:43 2009
@@ -13,7 +13,7 @@
       <link xlink:href="&url.pear.pepr;">PEPr system</link>.
     </para>
     <para>
-     All RFCs listed here have been accepted by the PEAR developers though
+     All RFCs listed here have been accepted by the PEAR developers through
      PEPr voting.
     </para>
   </partintro>
http://cvs.php.net/viewvc.cgi/peardoc/entities/global.ent?r1=1.13&r2=1.14&diff_format=u
Index: peardoc/entities/global.ent
diff -u peardoc/entities/global.ent:1.13 peardoc/entities/global.ent:1.14
--- peardoc/entities/global.ent:1.13	Mon May  4 14:03:34 2009
+++ peardoc/entities/global.ent	Mon May  4 19:41:43 2009
@@ -1,6 +1,6 @@
 <!-- -*- SGML -*-
 
- $Id: global.ent,v 1.13 2009/05/04 14:03:34 saltybeagle Exp $
+ $Id: global.ent,v 1.14 2009/05/04 19:41:43 cweiske Exp $
 
  Contains global "macros" for all the XML documents.
 
@@ -81,6 +81,7 @@
 <!ENTITY url.pear 'http://pear.php.net/'>
 <!ENTITY url.pear.account 'http://pear.php.net/accounts.php'>
 <!ENTITY url.pear.account.new 'http://pear.php.net/account-request.php'>
+<!ENTITY url.pear.bug 'http://pear.php.net/bugs/bug.php?id='>
 <!ENTITY url.pear.bugs 'http://pear.php.net/bugs/'>
 <!ENTITY url.pear.channels 'http://pear.php.net/channels/'>
 <!ENTITY url.pear.constitution.results 'http://pear.php.net/election/info.php?election=6&amp;results=1'>

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

    <date>2008-11-05</date>
  </info>

  <note>
    <para>
      The PEAR Group has voted and accepted this document. There will be
      no voting among developers.
    </para>
  </note>
  
  <para>
   This proposal has been in PEPr as
   <link xlink:href="&url.pear.pepr.proposal;538">proposal #538</link>.
  </para>

  <para>This RFC defines changes and enhancements to the <link
  linkend="standards">current Coding Standards</link> (CS) in PEAR. They are
  neccessary because the standards are not clear in some cases. With
  applications like <link
  xlink:href="&url.pear.package;PHP_CodeSniffer">PHP_CodeSniffer</link>
  being used, is is important that those issues are worked out and tools can
  deliver reliable warnings and CS errors.</para>

  <para>Most of the issues we currently have deal with long lines and how they
  should be split. General rule of thumb is that when splitting a line, the
  originating lines are indented by 4 spaces. Futher, the format shall allow
  it to easily comment out those lines - be it for debugging or development
  reasons. This implies that closing braces are to be put on a line on its
  own, and commas at the end of a line.</para>

  <para>While it might seem archaic to some, the 75-80 line rule is still
  important. Please see <link
  xlink:href="&url.linelength.paulmjones;">&url.linelength.paulmjones;</link>
  for an in-depth discussion on the topic.</para>

  <section xml:id="rfc.cs-enhancements.splitfuncdefs">
    <title>Split function definitions onto several lines</title>

    <para>Functions with many parameters need to be split onto several lines
    to keep the 80 chars/line limit. The first parameters may be put onto the
    same line as the function name if there is enough space. Subsequent
    parameters on following lines are to be indented 4 spaces. The closing
    parenthesis and the opening brace are to be put onto the next line, on the
    same indentation level as the "<token>function</token>" keyword.</para>

    <programlisting role="php"><![CDATA[<?php

function someFunctionWithAVeryLongName($firstParameter = 'something', $secondParameter = 'booooo',
    $third = null, $fourthParameter = false, $fifthParameter = 123.12,
    $sixthParam = true
) {
    //....
?>]]></programlisting>
  </section>

  <section xml:id="rfc.cs-enhancements.splitfunccall">
    <title>Split function call on several lines</title>

    <para>The CS require lines to have a maximum length of 80 chars. Calling
    functions or methods with many parameters while adhering to CS is
    impossible in that cases. It should be allowed to split parameters in
    function calls onto several lines.</para>

    <programlisting role="php"><![CDATA[<?php

$this->someObject->subObject->callThisFunctionWithALongName(
    $parameterOne, $parameterTwo,
    $aVeryLongParameterThree
);
?>]]></programlisting>

    <para>Several parameters per line should be allowed. Parameters need to be
    indented 4 spaces compared to the level of the function call. The opening
    parenthesis is to be put at the end of the function call line, the closing
    parenthesis gets its own line at the end of the parameters. This shows a
    visual end to the parameter indentations and follows the opening/closing
    brace rules for functions and conditionals. (See <link
    xlink:href="&url.pear.bug;11562">bug #11562</link>)</para>

    <para>The same applies not only for parameter variables, but also for
    nested function calls and for arrays.</para>

    <programlisting role="php"><![CDATA[<?php

$this->someObject->subObject->callThisFunctionWithALongName(
    $this->someOtherFunc(
        $this->someEvenOtherFunc(
            'Help me!',
            array(
                'foo'  => 'bar',
                'spam' => 'eggs',
            ),
            23
        ),
        $this->someEvenOtherFunc()
    ),
    $this->wowowowowow(12)
);
?>]]></programlisting>

    <para>Nesting those function parameters is allowed if it helps to make the
    code more readable, not only when it is necessary when the characters per
    line limit is reached.</para>

    <para>Using fluent application programming interfaces often leads to many
    concatenated function calls. Those calls may be split onto several lines.
    When doing this, all subsequent lines are indented by 4 spaces and begin
    with the "<literal>-&gt;</literal>" arrow.</para>

    <programlisting role="php"><![CDATA[<?php

$someObject->someFunction("some", "parameter")
    ->someOtherFunc(23, 42)
    ->andAThirdFunction();
?>]]></programlisting>
  </section>

  <section xml:id="rfc.cs-enhancements.splitlongassignments">
    <title>Split long assigments onto several lines</title>

    <para>Assigments may be split onto several lines when the character/line
    limit would be exceeded. The equal sign has to be positioned onto the
    following line, and indented by 4 characters.</para>

    <programlisting role="php"><![CDATA[<?php

$GLOBALS['TSFE']->additionalHeaderData[$this->strApplicationName]
    = $this->xajax->getJavascript(t3lib_extMgm::siteRelPath('nr_xajax'));
?>]]></programlisting>
  </section>

  <section xml:id="rfc.cs-enhancements.splitlongstatements">
    <title>Split long if statements onto several lines</title>

    <para>Long if statements may be split onto several lines when the
    character/line limit would be exceeded. The conditions have to be
    positioned onto the following line, and indented 4 characters. The logical
    operators (<literal>&amp;&amp;</literal>, <literal>||</literal>, etc.)
    should be at the beginning of the line to make it easier to comment (and
    exclude) the condition. The closing parenthesis and opening brace get
    their own line at the end of the conditions.</para>

    <para>Keeping the operators at the beginning of the line has two
    advantages: It is trivial to comment out a particular line during
    development while keeping syntactically correct code (except of course the
    first line). Further is the logic kept at the front where it's not
    forgotten. Scanning such conditions is very easy since they are aligned
    below each other.</para>

    <programlisting role="php"><![CDATA[<?php

if (($condition1
    || $condition2)
    && $condition3
    && $condition4
) {
    //code here
} 
?>]]></programlisting>

    <para>The first condition may be aligned to the others.</para>

    <programlisting role="php"><![CDATA[<?php

if (   $condition1
    || $condition2
    || $condition3
) {
    //code here
}
?>]]></programlisting>

    <para>The best case is of course when the line does not need to be split.
    When the if clause is really long enough to be split, it might be better
    to simplify it. In such cases, you could express conditions as variables
    an compare them in the <literal>if()</literal> condition. This has the
    benefit of "naming" and splitting the condition sets into smaller, better
    understandable chunks:</para>

    <programlisting role="php"><![CDATA[<?php

$is_foo = ($condition1 || $condition2);
$is_bar = ($condition3 && $condtion4);
if ($is_foo && $is_bar) {
    // ....
}
?>]]></programlisting>

    <note>
      <para>There were suggestions to indent the parantheses "groups" by 1
      space for each grouping. This is too hard to achieve in your coding
      flow, since your tab key always produces 4 spaces. Indenting the if
      clauses would take too much finetuning.</para>
    </note>
  </section>

  <section xml:id="rfc.cs-enhancements.ternaryoperators">
    <title>Ternary operators</title>

    <para>The same rule as for if clauses also applies for the <link
    xlink:href="http://php.net/ternary">ternary operator</link>: It may be
    split onto several lines, keeping the question mark and the colon at the
    front.</para>

    <programlisting role="php"><![CDATA[<?php

$a = $condition1 && $condition2
    ? $foo : $bar;

$b = $condition3 && $condition4
    ? $foo_man_this_is_too_long_what_should_i_do
    : $bar;
?>]]></programlisting>
  </section>

  <section xml:id="rfc.cs-enhancements.alignfuncparams">
    <title>Alignment of function parameters</title>

    <para>To support readability, parameters in subsequent calls to the same
    function/method may be aligned by parameter name:</para>

    <programlisting role="php"><![CDATA[<?php

$this->callSomeFunction('param1',     'second',        true);
$this->callSomeFunction('parameter2', 'third',         false);
$this->callSomeFunction('3',          'verrrrrrylong', true);
?>]]></programlisting>
  </section>

  <section xml:id="rfc.cs-enhancements.alignassignments">
    <title>Alignment of assignments</title>

    <para>To support readability, the equal signs may be aligned in
    block-related assignments:</para>

    <programlisting role="php"><![CDATA[<?php

$short  = foo($bar);
$longer = foo($baz);
?>]]></programlisting>

    <para>The rule can be broken when the length of the variable name is at
    least 8 characters longer/shorter than the previous one:</para>

    <programlisting role="php"><![CDATA[<?php

$short = foo($bar);
$thisVariableNameIsVeeeeeeeeeeryLong = foo($baz);
?>]]></programlisting>
  </section>

  <section xml:id="rfc.cs-enhancements.arrays">
    <title>Array formatting</title>

    <para>Assignments in arrays may be aligned. When splitting array
    definitions onto several lines, the last value may also have a trailing
    comma. This is valid PHP syntax and helps to keep code diffs
    minimal:</para>

    <programlisting role="php"><![CDATA[<?php

$some_array = array(
    'foo'  => 'bar',
    'spam' => 'ham',
);
?>]]></programlisting>
  </section>

  <section xml:id="rfc.cs-enhancements.recommendations">
    <title>Recommendations</title>

    <section xml:id="rfc.cs-enhancements.recommendations.readability">
      <title>Readability of code blocks</title>

      <para>Related lines of code should be grouped into blocks, seperated
      from each other to keep readability as high as possible. The definition
      of "related" depends on the code :)</para>

      <para>For example:</para>

      <programlisting role="php"><![CDATA[<?php

if ($foo) {
    $bar = 1;
}
if ($spam) {
    $ham = 1;
}
if ($pinky) {
    $brain = 1;
}
?>]]></programlisting>

      <para>is a lot easier to read when seperated:</para>

      <programlisting role="php"><![CDATA[<?php

if ($foo) {
    $bar = 1;
}

if ($spam) {
    $ham = 1;
}

if ($pinky) {
    $brain = 1;
}
?>]]></programlisting>
    </section>

    <section xml:id="rfc.cs-enhancements.recommendations.returnearly">
      <title>Return early</title>

      <para>To keep readability in functions and methods, it is wise to return
      early if simple conditions apply that can be checked at the beginning of
      a method:</para>

      <programlisting role="php"><![CDATA[<?php

function foo($bar, $baz)
{
    if ($foo) {
        //assume
        //that
        //here
        //is
        //the
        //whole
        //logic
        //of
        //this
        //method
        return $calculated_value;
    } else {
        return null;
    }
}
?>]]></programlisting>

      <para>It's better to return early, keeping indentation and brain power
      needed to follow the code low.</para>

      <programlisting role="php"><![CDATA[<?php

function foo($bar, $baz)
{
    if (!$foo) {
        return null;
    }

    //assume
    //that
    //here
    //is
    //the
    //whole
    //logic
    //of
    //this
    //method
    return $calculated_value;
}
?>]]></programlisting>
    </section>
  </section>

  <section xml:id="rfc.cs-enhancements.notes">
    <title>Notes</title>

    <para>We should keep to the 4 space indentation rule. Allowing 6, 8 or any
    other number for "personal preference" is an absurd line in a
    "standard".</para>

    <para>Of course, the best rule is keeping your code easy and clean, avoing
    dozens of parameters to a function ("code smell" for long parameter
    lists). But sometimes there is no way to avoid functions with 6
    parameters, and having default values for them does not simplfy the
    situation. The rules here are exactly for that code lines.</para>
  </section>
</chapter>