Estandarización
De CidesaWiki
(→Identación y Tamaño de Línea) |
(→Agregando mas opciones al uso de comentarios.) |
||
Línea 123: | Línea 123: | ||
Solo se debe tomar en cuenta que los bloques de código complicados deben ser documentados antes de que se nos olvide y tengamos que perder mas tiempo decifrando que hace. | Solo se debe tomar en cuenta que los bloques de código complicados deben ser documentados antes de que se nos olvide y tengamos que perder mas tiempo decifrando que hace. | ||
+ | Sintaxis estándar de editores para comentarios. | ||
+ | === Tareas === | ||
+ | Estructura de comentario de tareas. | ||
+ | <pre> | ||
+ | // @todo: Descripción de la tarea. | ||
+ | </pre> | ||
+ | === Correcciones === | ||
+ | Estructura de comentario de correciones. | ||
+ | <pre> | ||
+ | // FIXME: Descripción de la correción | ||
+ | </pre> | ||
+ | Al usar esta sintaxis se mostrará en el editor de la manera correcta a continuación se muestra un ejemplo de su uso en eclipse. | ||
+ | [[Archivo:Eclipse_tareas_y_correcciones.png]] | ||
== Codigo de Tags PHP == | == Codigo de Tags PHP == |
Última versión de 19:28 7 nov 2011
Se deben tomar en cuenta las siguientes reglas a la hora de crear código fuente:
Contenido |
Identación y Tamaño de Línea
Usa una identación de 2 espacios sin tabulaciones. Esto ayuda a mantener la integridad de los archivos dentro de los repositorios.
Es recomendable mantener lineas de aproximadamente 75-85 caracteres.
Estructuras de Control
Estas incluyen if, for, while, switch, etc. un ejemplo seria:
<?php if ((condition1) || (condition2)) { action1; } elseif ((condition3) && (condition4)) { action2; } else { defaultaction; } ?>
Las estrucuras de control deben tener un(1) espacio entre la instruccion y el paréntesis de apertura, para distinguir este de las funciones.
Para switch sería:
<?php switch (condition) { case 1: action1; break; case 2: action2; break; default: defaultaction; break; } ?>
Llamado a Funciones
Las funciones debe ser llamadas sin espacios entre el nombre de la función, el paŕentesis de apertura y el primer parámetro de la función; espacio entre la coma(,) y el parámetro, y ningun espacio entre el ultimo parámetro y el ultimo paréntesis. Ejemplo:
<?php $var = foo($bar, $baz, $quux); ?>
Para mejorar la lectura del código se puede colocar mas espacio entre la variable a asignar y la funcion, como por ejemplo:
<?php $short = foo($bar); $long_variable = foo($baz); ?>
Declaración de funciones
Por Ejemplo
<?php function fooFunction($arg1, $arg2 = '') { if (condition) { statement; } return $val; } ?>
Los argumentos con valor por defecto deben ser colocados al final de la lista de argumentos de la función. Por ejemplo:
<?php function connect(&$dsn, $persistent = false) { if (is_array($dsn)) { $dsninfo = &$dsn; } else { $dsninfo = DB::parseDSN($dsn); } if (!$dsninfo || !$dsninfo['phptype']) { return $this->raiseError(); } return true; } ?>
Comentarios
Los comentarios serán usados como normalmente los ofrece el lenguaje con el estilo C/C++, o sea, /* xxx */ y // xxx.
Solo se debe tomar en cuenta que los bloques de código complicados deben ser documentados antes de que se nos olvide y tengamos que perder mas tiempo decifrando que hace.
Sintaxis estándar de editores para comentarios.
Tareas
Estructura de comentario de tareas.
// @todo: Descripción de la tarea.
Correcciones
Estructura de comentario de correciones.
// FIXME: Descripción de la correción
Al usar esta sintaxis se mostrará en el editor de la manera correcta a continuación se muestra un ejemplo de su uso en eclipse.
Codigo de Tags PHP
Siempre usa <?php ?> para delimitar el codigo PHP.
Cabeceras de comentarios (PHPDocumentation)
Se debe usar la nomenclatura especificada en el articulo de [[../Documentación]]
Convencion de Nombre
- CLASES: Las clases deben tener nombre descriptivos. Evitando comolar abreviaciones donde sea posible. Los nombres de las clases deben colocar con la primera letra en mayuscula. Ejemplos
Log Net_Finger HTML_Upload_Error
- METODOS: Las funciones y métodos deben ser nombrados colocando como prefijo un nombre del paquete o grupo, seguido del nombre de la funcion con la primera letra en mayuscula, y cada palabra adicional debe ir con la primera letra mayuscula. No usa underscore "_" entre palabras descriptivas. Ejemplo:
conectar() getData() builtSomeWidget()
Constantes
Las constantes deben ser todas las letras UpperCase, con underscore para separar palabras. Ejemplo:
MAX = 1; COLUMNS = 4; COLUMN_NAME = "Column";
Ejemplo General
<?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 /** * 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 <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 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, 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: */ ?>