cvs: peardoc /ru/chapters standards.xml
[email protected] ("Christian Weiske")
| Newsgroups | php.pear.doc |
|---|---|
| Message-ID | <cvscweiske1244240381@cvsserver> |
cweiske Fri Jun 5 22:19:41 2009 UTC
Modified files:
/peardoc/ru/chapters standards.xml
Log:
Fix russian translation
cweiske-20090605221941.txt
(text/plain, 32.3 KB)
http://cvs.php.net/viewvc.cgi/peardoc/ru/chapters/standards.xml?r1=1.6&r2=1.7&diff_format=u
Index: peardoc/ru/chapters/standards.xml
diff -u peardoc/ru/chapters/standards.xml:1.6 peardoc/ru/chapters/standards.xml:1.7
--- peardoc/ru/chapters/standards.xml:1.6 Thu Oct 9 15:18:13 2008
+++ peardoc/ru/chapters/standards.xml Fri Jun 5 22:19:41 2009
@@ -450,5 +450,1000 @@
быть написаны в нижнем регистре.</para>
</section>
</section>
-
+
+ <section xml:id="standards.file"><info><title>File Formats</title></info>
+
+ <para>
+ All scripts contributed to PEAR must:
+ <itemizedlist>
+ <listitem>
+ <para>
+ Be stored as ASCII text
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Use ISO-8859-1 or UTF-8 character encoding. The encoding may be
+ declared using <literal>declare(encoding = 'utf-8');</literal> at the
+ top of the file.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Be Unix formatted
+ </para>
+ <para>
+ <quote>Unix formatted</quote> means two things:
+ </para>
+ <para>
+ 1) Lines must end only with a line feed (<literal>LF</literal>).
+ Line feeds are represented as
+ ordinal <literal>10</literal>,
+ octal <literal>012</literal> and
+ hex <literal>0A</literal>.
+ Do not use carriage returns (<literal>CR</literal>)
+ like Macintosh computers do
+ or the carriage return/line feed combination
+ (<literal>CRLF</literal>) like Windows computers do.
+ </para>
+ <para>
+ 2) There should be <emphasis>one</emphasis> line feed
+ after the closing PHP tag (<literal>?></literal>).
+ This means that when the cursor is at the very end
+ of the file, it should be <emphasis>one</emphasis>
+ line below the closing PHP tag.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section xml:id="standards.e_strict"><info><title><literal>E_STRICT</literal>-compatible code</title></info>
+
+ <para>
+ Starting on 01 January 2007, all new code that is suggested for
+ inclusion into PEAR must be
+ <literal>E_STRICT</literal>-compatible. This means that it must
+ not produce any warnings or errors when PHP's error reporting level
+ is set to <literal>E_ALL | E_STRICT</literal>.
+ </para>
+ <para>
+ The development of existing packages that are not
+ <literal>E_STRICT</literal>-compatible can continue as usual. If
+ however a new <emphasis>major</emphasis> version of the package is
+ released, this major version must then be
+ <literal>E_STRICT</literal>-compatible.
+ </para>
+ <para>
+ More details on this part of the Coding Standards can be found in
+ the <link linkend="rfc.estrict-compatibility">corresponding RFC</link>.
+ </para>
+ </section>
+
+ <section xml:id="standards.errors"><info><title>Error Handling Guidelines</title></info>
+
+
+
+ <para>
+ This part of the Coding Standards describes how errors are
+ handled in PEAR packages that are developed for PHP 5 and 6. It
+ uses Exceptions, introduced in PHP 5.0 with Zend Engine 2, as
+ the error handling mechanism.
+ </para>
+
+
+ <section><info><title>Definition of an error</title></info>
+
+
+ <para>
+ An error is defined as an unexpected, invalid program state from
+ which it is impossible to recover. For the sake of definition,
+ recovery scope is defined as the method scope. Incomplete
+ recovery is considered a recovery.
+ </para>
+
+ <example><info><title>One pretty straightforward example for an error</title></info>
+
+ <programlisting role="php">
+ <![CDATA[
+/*
+ * Connect to Specified Database
+ *
+ * @throws Example_Datasource_Exception when it can't connect
+ * to specified DSN.
+ */
+function connectDB($dsn)
+{
+ $this->db =& DB::connect($dsn);
+ if (DB::isError($this->db)) {
+ throw new Example_Datasource_Exception(
+ "Unable to connect to $dsn:" . $this->db->getMessage()
+ );
+ }
+}
+ ]]>
+ </programlisting>
+ </example>
+
+ <para>
+ In this example the objective of the method is to connect to the
+ given DSN. Since it can't do anything but ask PEAR DB to do it,
+ whenever DB returns an error, the only option is to bail out and
+ launch the exception.
+ </para>
+
+ <example><info><title>Error handling with recovery</title></info>
+
+
+ <programlisting role="php">
+ <![CDATA[
+/*
+ * Connect to one of the possible databases
+ *
+ * @throws Example_Datasource_Exception when it can't connect to
+ * any of the configured databases.
+ *
+ * @throws Example_Config_Exception when it can't find databases
+ * in the configuration.
+ */
+
+function connect(Config $conf)
+{
+ $dsns =& $conf->searchPath(array('config', 'db'));
+ if ($dsns === FALSE) throw new Example_Config_Exception(
+ 'Unable to find config/db section in configuration.'
+ );
+
+ $dsns =& $dsns->toArray();
+
+ foreach($dsns as $dsn) {
+ try {
+ $this->connectDB($dsn);
+ return;
+ } catch (Example_Datasource_Exception e) {
+ // Some warning/logging code recording the failure
+ // to connect to one of the databases
+ }
+ }
+ throw new Example_Datasource_Exception(
+ 'Unable to connect to any of the configured databases'
+ );
+}
+ ]]>
+ </programlisting>
+ </example>
+
+ <para>
+ This second example shows an exception being caught and
+ recovered from. Although the lower level
+ <function>connectDB</function> method is unable to do anything
+ but throw an error when one database connection fails, the upper
+ level <function>connect</function> method knows the object can
+ go by with any one of the configured databases. Since the error
+ was recovered from, the exception is silenced at this level and
+ not rethrown.
+ </para>
+
+ <example><info><title>Incomplete recovery</title></info>
+
+
+ <programlisting role="php">
+ <![CDATA[
+/*
+ * loadConfig parses the provided configuration. If the configuration
+ * is invalid, it will set the configuration to the default config.
+ *
+ */
+function loadConfig(Config $conf)
+{
+ try {
+ $this->config = $conf->parse();
+ } catch (Config_Parse_Exception e) {
+ // Warn/Log code goes here
+ // Perform incomplete recovery
+ $this->config = $this->defaultConfig;
+ }
+}
+ ]]>
+ </programlisting>
+ </example>
+
+ <para>
+ The recovery produces side effects, so it is considered
+ incomplete. However, the program may proceed, so the exception
+ is considered handled, and must not be rethrown. As in the
+ previous example, when silencing the exception, logging or
+ warning should occur.
+ </para>
+ </section>
+
+ <section><info><title>Error Signaling in PHP 5 PEAR packages</title></info>
+
+
+ <para>
+ Error conditions in PEAR packages written for PHP 5 must be
+ signaled using exceptions. Usage of return codes or return
+ <classname>PEAR_Error</classname> objects is deprecated in favor
+ of exceptions. Naturally, packages providing compatibility with
+ PHP 4 do not fall under these coding guidelines, and may thus
+ use the error handling mechanisms defined in the PHP 4 PEAR
+ coding guidelines.
+ </para>
+ <para>
+ An exception should be thrown whenever an error condition is
+ met, according to the definition provided in the previous
+ section. The thrown exception should contain enough information
+ to debug the error and quickly identify the error cause. Note
+ that, during production runs, no exception should reach the
+ end-user, so there is no need for concern about technical
+ complexity in the exception error messages.
+ </para>
+ <para>
+ The basic <classname>PEAR_Exception</classname> contains a
+ textual error, describing the program state that led to the
+ throw and, optionally, a wrapped lower level exception,
+ containing more info on the lower level causes of the error.
+ </para>
+ <para>
+ The kind of information to be included in the exception is
+ dependent on the error condition. From the point of view of
+ exception throwing, there are three classes of error conditions:
+ </para>
+
+ <orderedlist>
+ <listitem>
+ <simpara>
+ Errors detected during precondition checks
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ Lower level library errors signaled via error return codes
+ or error return objects
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ Uncorrectable lower library exceptions
+ </simpara>
+ </listitem>
+ </orderedlist>
+
+ <para>
+ Errors detected during precondition checks should contain a
+ description of the failed check. If possible, the description
+ should contain the violating value. Naturally, no wrapped
+ exception can be included, as there isn't a lower level cause of
+ the error. Example:
+ </para>
+
+ <example><info><title/></info>
+
+ <programlisting role="php">
+ <![CDATA[
+function divide($x, $y)
+{
+ if ($y == 0) {
+ throw new Example_Aritmetic_Exception('Division by zero');
+ }
+}
+ ]]>
+ </programlisting>
+ </example>
+
+ <para>
+ Errors signaled via return codes by lower level libraries, if
+ unrecoverable, should be turned into exceptions. The error
+ description should try to convey all information contained in
+ the original error. One example, is the connect method
+ previously presented:
+ </para>
+
+ <example><info><title/></info>
+
+ <programlisting role="php">
+ <![CDATA[
+/*
+ * Connect to Specified Database
+ *
+ * @throws Example_Datasource_Exception when it can't connect to specified DSN.
+ */
+function connectDB($dsn)
+{
+ $this->db =& DB::connect($dsn);
+ if (DB::isError($this->db)) {
+ throw new Example_Datasource_Exception(
+ "Unable to connect to $dsn:" . $this->db->getMessage()
+ );
+ }
+}
+ ]]>
+ </programlisting>
+ </example>
+
+ <para>
+ Lower library exceptions, if they can't be corrected, should
+ either be rethrown or bubbled up. When rethrowing, the original
+ exception must be wrapped inside the one being thrown. When
+ letting the exception bubble up, the exception just isn't
+ handled and will continue up the call stack in search of a
+ handler.
+ </para>
+
+ <example><info><title>Rethrowing an exception</title></info>
+
+
+ <programlisting role="php">
+ <![CDATA[
+function preTaxPrice($retailPrice, $taxRate)
+{
+ try {
+ return $this->divide($retailPrice, 1 + $taxRate);
+ } catch (Example_Aritmetic_Exception e) {
+ throw new Example_Tax_Exception('Invalid tax rate.', e);
+ }
+}
+ ]]>
+ </programlisting>
+ </example>
+
+ <example><info><title>Letting exceptions bubble up</title></info>
+
+
+ <programlisting role="php">
+ <![CDATA[
+function preTaxPrice($retailPrice, $taxRate)
+{
+ return $this->divide($retailPrice, 1 + $taxRate);
+}
+ ]]>
+ </programlisting>
+ </example>
+
+ <para>
+ The case between rethrowing or bubbling up is one of software
+ architecture: Exceptions should be bubbled up, except in these
+ two cases:
+ </para>
+
+ <orderedlist>
+ <listitem>
+ <simpara>
+ The original exception is from another package. Letting it
+ bubble up would cause implementation details to be exposed,
+ violating layer abstraction, conducing to poor design.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ The current method can add useful debugging information to
+ the received error before rethrowing.
+ </simpara>
+ </listitem>
+ </orderedlist>
+ </section>
+
+ <section><info><title>Exceptions and normal program flow</title></info>
+
+
+ <para>
+ Exceptions should never be used as normal program flow. If
+ removing all exception handling logic (try-catch statements)
+ from the program, the remaining code should represent the
+ "One True Path" -- the flow that would be executed in
+ the absence of errors.
+ </para>
+ <para>
+ This requirement is equivalent to requiring that exceptions be
+ thrown only on error conditions, and never in normal program
+ states.
+ </para>
+ <para>
+ One example of a method that wrongly uses the bubble up
+ capability of exceptions to return a result from a deep
+ recursion:
+ </para>
+
+ <example><info><title/></info>
+
+ <programlisting role="php">
+ <![CDATA[
+/**
+ * Recursively search a tree for string.
+ * @throws ResultException
+ */
+public function search(TreeNode $node, $data)
+{
+ if ($node->data === $data) {
+ throw new ResultException( $node );
+ } else {
+ search( $node->leftChild, $data );
+ search( $node->rightChild, $data );
+ }
+}
+ ]]>
+ </programlisting>
+ </example>
+
+ <para>
+ In the example the ResultException is simply using the
+ "eject!" qualities of exception handling to jump out
+ of deeply nested recursion. When actually used to signify an
+ error this is a very powerful feature, but in the example above
+ this is simply lazy development.
+ </para>
+ </section>
+
+ <section><info><title>Exception class hierarchies</title></info>
+
+
+ <para>
+ All of PEAR packages exceptions must be descendant from
+ <classname>PEAR_Exception</classname>. <classname>PEAR_Exception</classname>
+ provides exception wrapping abilities, absent from the top level
+ PHP Exception class, and needed to comply with the previous
+ section requirements.
+ </para>
+ <para>
+ Additionally, each PEAR package must provide a top level
+ exception, named <Package_Name>_Exception. It is
+ considered best practice that the package never throws
+ exceptions that aren't descendant from its top level exception.
+ </para>
+ </section>
+
+ <section><info><title>Documenting Exceptions</title></info>
+
+
+ <para>
+ Because PHP, unlike Java, does not require you to explicitly
+ state which exceptions a method throws in the method signature,
+ it is critical that exceptions be thoroughly documented in your
+ method headers.
+ </para>
+
+ <example><info><title>
+ Exceptions should be documented using the
+ <literal>@throws</literal> phpdoc keyword
+ </title></info>
+
+
+ <programlisting role="php">
+ <![CDATA[
+/**
+ * This method searches for aliens.
+ *
+ * @return array Array of Aliens objects.
+ * @throws AntennaBrokenException If the impedence readings indicate
+ * that the antenna is broken.
+ *
+ * @throws AntennaInUseException If another process is using the
+ * antenna already.
+ */
+public function findAliens($color = 'green');
+ ]]>
+ </programlisting>
+ </example>
+
+ <para>
+ In many cases middle layers of an application will rewrap any
+ lower-level exceptions into more meaningful application
+ exceptions. This also needs to be made clear:
+ </para>
+
+ <example><info><title/></info>
+
+ <programlisting role="php">
+ <![CDATA[
+/**
+ * Load session objects into shared memory.
+ *
+ * @throws LoadingException Any lower-level IOException will be wrapped
+ * and re-thrown as a LoadingException.
+ */
+public function loadSessionObjects();
+ ]]>
+ </programlisting>
+ </example>
+
+ <para>
+ In other cases your method may simply be a conduit through which
+ lower level exceptions can pass freely. As challenging as it may
+ be, your method should also document which exceptions it is
+ <emphasis>not</emphasis> catching.
+ </para>
+
+ <example><info><title/></info>
+
+ <programlisting role="php">
+ <![CDATA[
+/**
+ * Performs a batch of database queries (atomically, not in transaction).
+ * @throws SQLException Low-level SQL errors will bubble up through this method.
+ */
+public function batchExecute();
+ ]]>
+ </programlisting>
+ </example>
+ </section>
+
+ <section><info><title>Exceptions as part of the API</title></info>
+
+
+ <para>
+ Exceptions play a critical role in the API of your
+ library. Developers using your library
+ <emphasis>depend</emphasis> on accurate descriptions of where
+ and why exceptions might be thrown from your
+ package. Documentation is critical. Also maintaining the types
+ of messages that are thrown is also an important requirement for
+ maintaining backwards-compatibility.
+ </para>
+ <para>
+ Because Exceptions are critical to the API of your package, you
+ must ensure that you don't break backwards compatibility (BC) by
+ making changes to exceptions.
+ </para>
+ <para>
+ Things that break BC include:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ Any change to which methods throw exceptions.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ A change whereby a method throws an exception higher in the
+ inheritance tree. For example, if you changed your method to
+ throw a <classname>PEAR_Exception</classname> rather than a
+ <classname>PEAR_IOException</classname>, you would be
+ breaking backwards compatibility.
+ </simpara>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ Things that do not break BC:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ Throwing a subclass of the original exception. For example,
+ changing a method to throw
+ <classname>PEAR_IOException</classname> when before it had
+ been throwing <classname>PEAR_Exception</classname> would
+ not break BC (provided that
+ <classname>PEAR_IOException</classname> extends
+ <classname>PEAR_Exception</classname>).
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ </section>
+ </section>
+
+
+ <section xml:id="standards.bestpractices">
+ <info>
+ <title>Best practices</title>
+ </info>
+
+ <para>
+ There are other things not covered by PEAR Coding Standards which
+ are mostly subject of personal preference and not directly related
+ to readability of the code. Things like "single quotes vs double
+ quotes" are features of PHP itself to make programming easier and
+ there are no reasons not use one way in preference to another. Such
+ best practices are left solely on developer to decide. The only
+ recommendation could be made to keep consistency within package
+ and respect personal style of other developers.
+ </para>
+
+
+ <section xml:id="standards.bestpractices.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="standards.bestpractices.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="standards.sample">
+ <info>
+ <title>Sample File (including Docblock Comment standards)</title>
+ </info>
+
+ <para>
+ The source code of PEAR packages are read by thousands
+ of people. Also, it is likely other people will become
+ developers on your package at some point in the future.
+ Therefore, it is important to make life easier for
+ everyone by formatting the code and docblocks in
+ standardized ways. People can then quickly find the
+ information they are looking for because it is in the
+ expected location. Your cooperation is appreciated.
+ </para>
+ <para>
+ Each docblock in the example contains many details about writing
+ Docblock Comments.
+ Following those instructions is important for two reasons.
+ First, when docblocks are easy to read, users and developers can quickly
+ ascertain what your code does.
+ Second, the PEAR website now contains the phpDocumentor generated
+ documentation for each release of each package, so keeping things straight
+ here means the API docs on the website will be useful.
+ </para>
+ <para>
+ Please take note of the vertical and horizontal spacing.
+ They are part of the standard.
+ </para>
+ <para>
+ The <quote>fold markers</quote> (<literal>// {{{</literal> and
+ <literal>// }}}</literal>) are optional.
+ If you aren't using fold markers,
+ remove <literal>foldmethod=marker</literal> from the vim header.
+ </para>
+ <para>
+ <programlisting role="php">
+ <![CDATA[
+<?php
+
+/* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */
+
+/**
+ * Short description for file
+ *
+ * Long description for file (if any)...
+ *
+ * PHP version 5
+ *
+ * LICENSE: This source file is subject to version 3.01 of the PHP license
+ * that is available through the world-wide-web at the following URI:
+ * http://www.php.net/license/3_01.txt. If you did not receive a copy of
+ * the PHP License and are unable to obtain it through the web, please
+ * send a note to [email protected] so we can mail you a copy immediately.
+ *
+ * @category CategoryName
+ * @package PackageName
+ * @author Original Author <[email protected]>
+ * @author Another Author <[email protected]>
+ * @copyright 1997-2005 The PHP Group
+ * @license http://www.php.net/license/3_01.txt PHP License 3.01
+ * @version CVS: ]]>$<![CDATA[Id:$
+ * @link http://pear.php.net/package/PackageName
+ * @see NetOther, Net_Sample::Net_Sample()
+ * @since File available since Release 1.2.0
+ * @deprecated File deprecated in Release 2.0.0
+ */
+
+/**
+ * This is a "Docblock Comment," also known as a "docblock." The class'
+ * docblock, below, contains a complete description of how to write these.
+ */
+require_once 'PEAR.php';
+
+// {{{ constants
+
+/**
+ * Methods return this if they succeed
+ */
+define('NET_SAMPLE_OK', 1);
+
+// }}}
+// {{{ GLOBALS
+
+/**
+ * The number of objects created
+ * @global int $GLOBALS['_NET_SAMPLE_Count']
+ */
+$GLOBALS['_NET_SAMPLE_Count'] = 0;
+
+// }}}
+// {{{ Net_Sample
+
+/**
+ * An example of how to write code to PEAR's standards
+ *
+ * Docblock comments start with "/**" at the top. Notice how the "/"
+ * lines up with the normal indenting and the asterisks on subsequent rows
+ * are in line with the first asterisk. The last line of comment text
+ * should be immediately followed on the next line by the closing asterisk
+ * and slash and then the item you are commenting on should be on the next
+ * line below that. Don't add extra lines. Please put a blank line
+ * between paragraphs as well as between the end of the description and
+ * the start of the @tags. Wrap comments before 80 columns in order to
+ * ease readability for a wide variety of users.
+ *
+ * Docblocks can only be used for programming constructs which allow them
+ * (classes, properties, methods, defines, includes, globals). See the
+ * phpDocumentor documentation for more information.
+ * http://phpdoc.org/docs/HTMLSmartyConverter/default/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html
+ *
+ * The Javadoc Style Guide is an excellent resource for figuring out
+ * how to say what needs to be said in docblock comments. Much of what is
+ * written here is a summary of what is found there, though there are some
+ * cases where what's said here overrides what is said there.
+ * http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#styleguide
+ *
+ * The first line of any docblock is the summary. Make them one short
+ * sentence, without a period at the end. Summaries for classes, properties
+ * and constants should omit the subject and simply state the object,
+ * because they are describing things rather than actions or behaviors.
+ *
+ * Below are the tags commonly used for classes. @category through @version
+ * are required. The remainder should only be used when necessary.
+ * Please use them in the order they appear here. phpDocumentor has
+ * several other tags available, feel free to use them.
+ *
+ * @category CategoryName
+ * @package PackageName
+ * @author Original Author <[email protected]>
+ * @author Another Author <[email protected]>
+ * @copyright 1997-2005 The PHP Group
+ * @license http://www.php.net/license/3_01.txt PHP License 3.01
+ * @version Release: @package_version@
+ * @link http://pear.php.net/package/PackageName
+ * @see NetOther, Net_Sample::Net_Sample()
+ * @since Class available since Release 1.2.0
+ * @deprecated Class deprecated in Release 2.0.0
+ */
+class Net_Sample
+{
+ // {{{ properties
+
+ /**
+ * The status of foo's universe
+ *
+ * Potential values are 'good', 'fair', 'poor' and 'unknown'.
+ *
+ * @var string
+ */
+ var $foo = 'unknown';
+
+ /**
+ * The status of life
+ *
+ * Note that names of private properties or methods must be
+ * preceeded by an underscore.
+ *
+ * @var bool
+ * @access private
+ */
+ var $_good = true;
+
+ // }}}
+ // {{{ setFoo()
+
+ /**
+ * Registers the status of foo's universe
+ *
+ * Summaries for methods should use 3rd person declarative rather
+ * than 2nd person imperative, beginning with a verb phrase.
+ *
+ * Summaries should add description beyond the method's name. The
+ * best method names are "self-documenting", meaning they tell you
+ * basically what the method does. If the summary merely repeats
+ * the method name in sentence form, it is not providing more
+ * information.
+ *
+ * Summary Examples:
+ * + Sets the label (preferred)
+ * + Set the label (avoid)
+ * + This method sets the label (avoid)
+ *
+ * Below are the tags commonly used for methods. A @param tag is
+ * required for each parameter the method has. The @return
+ * and @access tags are mandatory. The @throws tag is required if
+ * the method uses exceptions. @static is required if the method can
+ * be called statically. The remainder should only be used when
+ * necessary. Please use them in the order they appear here.
+ * phpDocumentor has several other tags available, feel free to use
+ * them.
+ *
+ * The @param tag contains the data type, then the parameter's
+ * name, followed by a description. By convention, the first noun in
+ * the description is the data type of the parameter. Articles like
+ * "a", "an", and "the" can precede the noun. The descriptions
+ * should start with a phrase. If further description is necessary,
+ * follow with sentences. Having two spaces between the name and the
+ * description aids readability.
+ *
+ * When writing a phrase, do not capitalize and do not end with a
+ * period:
+ * + the string to be tested
+ *
+ * When writing a phrase followed by a sentence, do not capitalize the
+ * phrase, but end it with a period to distinguish it from the start
+ * of the next sentence:
+ * + the string to be tested. Must use UTF-8 encoding.
+ *
+ * Return tags should contain the data type then a description of
+ * the data returned. The data type can be any of PHP's data types
+ * (int, float, bool, string, array, object, resource, mixed)
+ * and should contain the type primarily returned. For example, if
+ * a method returns an object when things work correctly but false
+ * when an error happens, say 'object' rather than 'mixed.' Use
+ * 'void' if nothing is returned.
+ *
+ * Here's an example of how to format examples:
+ * <code>
+ * require_once 'Net/Sample.php';
+ *
+ * $s = new Net_Sample();
+ * if (PEAR::isError($s)) {
+ * echo $s->getMessage() . "\n";
+ * }
+ * </code>
+ *
+ * Here is an example for non-php example or sample:
+ * <samp>
+ * pear install net_sample
+ * </samp>
+ *
+ * @param string $arg1 the string to quote
+ * @param int $arg2 an integer of how many problems happened.
+ * Indent to the description's starting point
+ * for long ones.
+ *
+ * @return int the integer of the set mode used. FALSE if foo
+ * foo could not be set.
+ * @throws exceptionclass [description]
+ *
+ * @access public
+ * @static
+ * @see Net_Sample::$foo, Net_Other::someMethod()
+ * @since Method available since Release 1.2.0
+ * @deprecated Method deprecated in Release 2.0.0
+ */
+ function setFoo($arg1, $arg2 = 0)
+ {
+ /*
+ * This is a "Block Comment." The format is the same as
+ * Docblock Comments except there is only one asterisk at the
+ * top. phpDocumentor doesn't parse these.
+ */
+ if ($arg1 == 'good' || $arg1 == 'fair') {
+ $this->foo = $arg1;
+ return 1;
+ } elseif ($arg1 == 'poor' && $arg2 > 1) {
+ $this->foo = 'poor';
+ return 2;
+ } else {
+ return false;
+ }
+ }
+
+ // }}}
+}
+
+// }}}
+
+/*
+ * Local variables:
+ * tab-width: 4
+ * c-basic-offset: 4
+ * c-hanging-comment-ender-p: nil
+ * End:
+ */
+
+?>
+ ]]>
+ </programlisting>
+ </para>
+ </section>
+
+
+ <section xml:id="standards.toolbox">
+ <info>
+ <title>The PEAR toolbox</title>
+ </info>
+
+ <para>
+ PEAR provides some tools to help developers keep their code clean
+ and free of coding standards related errors.
+ </para>
+ <para>
+ For one there is
+ <link linkend="package.php.php-codesniffer">PHP_CodeSniffer</link>
+ which can be used to detect coding standard errors in your scripts.
+ Further, whole PEAR CVS repository is checked each night for violations
+ - the results can be found at
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.qa.cweiske.overview;">PEAR QA results overview page</link>
+ as well as on the linked subpages which explain the errors in detail.
+ </para>
+ </section>
+
</chapter>