Estandarización - Historial de revisiones

Neftaliyagua: /* Agregando mas opciones al uso de comentarios.*/

2011-11-07T19:28:38Z

Agregando mas opciones al uso de comentarios.

← Revisión anterior		Revisión de 19:28 7 nov 2011
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 ==

Desi: /* Identación y Tamaño de Línea */

2007-04-18T15:47:35Z

Identación y Tamaño de Línea

← Revisión anterior		Revisión de 15:47 18 abr 2007
Línea 3:		Línea 3:
	== Identación y Tamaño de Línea ==		== Identación y Tamaño de Línea ==

-	Usa una identación de 4 espacios sin tabulaciones. Esto ayuda a mantener la integridad de los archivos dentro de los repositorios.	+	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.		Es recomendable mantener lineas de aproximadamente 75-85 caracteres.
-

	== Estructuras de Control ==		== Estructuras de Control ==

Lhernandez: /* Cabeceras de comentarios (PHPDocumentation) */

2007-04-18T15:36:22Z

Cabeceras de comentarios (PHPDocumentation)

← Revisión anterior		Revisión de 15:36 18 abr 2007
Línea 132:		Línea 132:
	== Cabeceras de comentarios (PHPDocumentation) ==		== Cabeceras de comentarios (PHPDocumentation) ==

-	Se debe usar la nomenclatura especificada en el articulo de [[~~Documentación~~ ../Documentación]]	+	Se debe usar la nomenclatura especificada en el articulo de [[../Documentación]]

	== Convencion de Nombre ==		== Convencion de Nombre ==

Lhernandez: /* Cabeceras de comentarios (PHPDocumentation) */

2007-04-18T15:36:10Z

Cabeceras de comentarios (PHPDocumentation)

← Revisión anterior		Revisión de 15:36 18 abr 2007
Línea 132:		Línea 132:
	== Cabeceras de comentarios (PHPDocumentation) ==		== Cabeceras de comentarios (PHPDocumentation) ==

-	Se debe usar la nomenclatura especificada en el articulo de [[../~~Documentación~~ Documentación]]	+	Se debe usar la nomenclatura especificada en el articulo de [[Documentación ../Documentación]]

	== Convencion de Nombre ==		== Convencion de Nombre ==

Lhernandez: /* Cabeceras de comentarios (PHPDocumentation) */

2007-04-18T15:35:58Z

Cabeceras de comentarios (PHPDocumentation)

← Revisión anterior		Revisión de 15:35 18 abr 2007
Línea 132:		Línea 132:
	== Cabeceras de comentarios (PHPDocumentation) ==		== Cabeceras de comentarios (PHPDocumentation) ==

-	Se debe usar la nomenclatura especificada en el articulo de [[/Documentación]]	+	Se debe usar la nomenclatura especificada en el articulo de [[../Documentación Documentación]]

	== Convencion de Nombre ==		== Convencion de Nombre ==

Lhernandez: /* Cabeceras de comentarios (PHPDocumentation) */

2007-04-18T15:35:19Z

Cabeceras de comentarios (PHPDocumentation)

← Revisión anterior		Revisión de 15:35 18 abr 2007
Línea 132:		Línea 132:
	== Cabeceras de comentarios (PHPDocumentation) ==		== Cabeceras de comentarios (PHPDocumentation) ==

-	Se debe usar la nomenclatura especificada en el articulo de [Documentación]	+	Se debe usar la nomenclatura especificada en el articulo de [[/Documentación]]
-		+

	== Convencion de Nombre ==		== Convencion de Nombre ==

Lhernandez en 15:32 18 abr 2007

2007-04-18T15:32:47Z

← Revisión anterior		Revisión de 15:32 18 abr 2007
Línea 1:		Línea 1:
-	Se deben tomar en cuenta las siguientes reglas a la hora de crear código fuente:	+	'''Se deben tomar en cuenta las siguientes reglas a la hora de crear código fuente:'''
-		+

	== Identación y Tamaño de Línea ==		== Identación y Tamaño de Línea ==

Lhernandez: New page: Se deben tomar en cuenta las siguientes reglas a la hora de crear código fuente: == Identación y Tamaño de Línea == Usa una identación de 4 espacios sin tabulaciones. Esto ayuda a ...

2007-04-18T15:31:49Z

New page: Se deben tomar en cuenta las siguientes reglas a la hora de crear código fuente: == Identación y Tamaño de Línea == Usa una identación de 4 espacios sin tabulaciones. Esto ayuda a ...

Página nueva

Se deben tomar en cuenta las siguientes reglas a la hora de crear código fuente:

== Identación y Tamaño de Línea ==

Usa una identación de 4 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:

<pre>

<?php
if ((condition1) || (condition2)) {
action1;
} elseif ((condition3) && (condition4)) {
action2;
} else {
defaultaction;
}
?>

</pre>

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:

<pre>

<?php
switch (condition) {
case 1:
action1;
break;

case 2:
action2;
break;

default:
defaultaction;
break;
}
?>

</pre>

== 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:

<pre>

<?php
$var = foo($bar, $baz, $quux);
?>

</pre>

Para mejorar la lectura del código se puede colocar mas espacio entre la variable a asignar y la funcion, como por ejemplo:

<pre>

<?php
$short = foo($bar);
$long_variable = foo($baz);
?>

</pre>

== Declaración de funciones ==

Por Ejemplo

<pre>

<?php
function fooFunction($arg1, $arg2 = '')
{
if (condition) {
statement;
}
return $val;
}
?>

</pre>

Los argumentos con valor por defecto deben ser colocados al final de la lista de argumentos de la función. Por ejemplo:

<pre>

<?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;
}
?>

</pre>

== 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.

== 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

<pre>
Log
Net_Finger
HTML_Upload_Error
</pre>

* 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:

<pre>
conectar()
getData()
builtSomeWidget()
</pre>

== Constantes ==

Las constantes deben ser todas las letras UpperCase, con underscore para separar palabras. Ejemplo:

<pre>
MAX = 1;
COLUMNS = 4;
COLUMN_NAME = "Column";
</pre>

== Ejemplo General ==

<pre>

<?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:
*/

?>

</pre>