PEAR: Estándares de desarrollo para PHP (ejemplo)

29 03 2007

En la entrada anterior hablamos acerca de los estándares de programación propustos por el proyecto PEAR, ahora, les muestro un ejemplo práctico, extraído de la página del proyecto, indicando como quedaría un script PHP, utlizando estándares:

<?php

/* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */

/**
 * Short description for file
 *
 * Long description for file (if any)…
 *
 * PHP versions 4 and 5
 *
 * LICENSE: This source file is subject to version 3.0 of the PHP
 * license that is available through the world-wide-web at the
 * following URI: http://www.php.net/license/3_0.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 license@php.net so we can
 * mail you a copy immediately.
 *
 * @category CategoryName
 * @package PackageName
 * @author Original Author <author@example.com>
 * @author Another Author <another@example.com>
 * @copyright 1997-2005 The PHP Group
 * @license http://www.php.net/license/3_0.txt PHP License 3.0
 * @version CVS: $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

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, begining 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:
*/

?>

Pueden ver el documento completo referente a estándares desde está ubicación.

embargo, existe una técnica que consiste en declarar valores por defecto en la hoja CSS para que los exploradores puedan renderizar correctamente nuestro estilo, además de algunas técnicas importantes para que podamos realizar hojas de estilo flexibles y adaptables.

Comentando el código: Es importante que el archivo de estilos esté documentado. Según la propuesta de Andy Budd, es importante incluir un número de versión, dirección de correo electrónico, etc. con el objetivo de hacer fácil el mantenimiento y control de cambios.

Decidiendo como dividir las hojas de estilo: Muchos de nosotros, solemos utilizar una única hoja de estilo para el diseño de todo un sitio. Esto no es muy adecuado, dado que lo que estamos haciendo es desperdiciando ancho de banda, cada vez que una página es solicitada, mandando toda una hoja de estilos cuando la página requerida solamente utiliza unos cuantos. Una buena técnica consiste en dividir en secciones una hoja de estilos: podemos utilizar una por pagina, agrupando elementos más comunes en una sola y dejando el resto, en distintas. Tambien, podemos importar más hojas de estilo, desde el CSS con el atributo @import.

Remueva estilos por defecto: asigne valores por defecto a algunas de los valores CSS por defecto como margin, border y padding. La razón es simple, cada explorador aplica estilos distintos a distintos elementos.

Cree clases para elementos flotantes: si utiliza DIV’s para maquetar, sabrá que la manera para hacer que un elemento este a la par del otro y no caiga a la linea siguiente es con el atributo FLOAT. Pues bien, una buena práctica sería crear clases con esos atributos, incluyendo el elemento CLEAR.

Configure el documento: otra buena práctica para comenzar a aplicar el estilo tipográfico a un documento, es hacerlo desde el mismo elemento BODY. Además, la propuesta de Richard Rutter es que utilicemos tipos EMS para el tamaño de fuente, pues esto nos permitirá tener un mejor control para la tipografía.

También, asigne fuentes por defecto. Debemos de saber que le tamaño por defecto es de 10pt.

Cree secciones: archivos CSS demasiado extensos pueden ser dificiles de manejar. Es recomendable, dividirlo en varias secciones con estilos y clases comunes para cada sección. Por ejemplo, divida las clases de los elementos de navegación, de los estilos de los elementos de pie de página, etc.

Formas y Tablas: por defecto, es preferible asignarle estilo a los cuadros de texto. Puede asignarsele un valor al padding del objeto para que el texto sea más legible. Para las tablas, talvez lo principal sería indicarle un valor por defecto al tipo de letra y a los borders.

Por lo demás, el archivo XHTML resultante, debería tener disponible una versión imprimible, iconos y RSS feeds

Acerca de este Artículo: este artículo es una versión traducida y adaptada del artículo original, publicado en el sitio Shape Shed en colaboración con George Ornbo y licenciado bajo la especificación de Creative Commons.

Artículos Relacionados:


Acciones

Information

2 responses

28 05 2010
Berta Neff

Really interesting post. Honest!

30 05 2010
Stacy Wolf

If I had a dollar for every time I came to dotpress.wordpress.com.. Incredible writing.

Responder

Introduce tus datos o haz clic en un icono para iniciar sesión:

Logo de WordPress.com

Estás comentando usando tu cuenta de WordPress.com. Cerrar sesión / Cambiar )

Imagen de Twitter

Estás comentando usando tu cuenta de Twitter. Cerrar sesión / Cambiar )

Foto de Facebook

Estás comentando usando tu cuenta de Facebook. Cerrar sesión / Cambiar )

Google+ photo

Estás comentando usando tu cuenta de Google+. Cerrar sesión / Cambiar )

Conectando a %s




A %d blogueros les gusta esto: