Buenas, en ésta entrada explicaré las reglas básicas a la hora de desarrollar un componente,
Les recuerdo que como minimo deben tener buenos conocimientos de Programación Orientada a Objetos, sobre le patrón MVC y otras cosas que serán explicadas luego.
Cuando adquieran esos conocimientos podrían empezar a plantearse el desarrollo de un componente.
Hablaremos entonces sobre Components Interface division.
Como dije en una entrada anterior, los componentes se dividen en 3 partes, en ésta entrada explicaremos la segunda división (Interface) y su razón de existir.
La razón de la existencia de la interface, es parte de la respuesta a una busqueda que hago hace un tiempo, se dice que el código debe hablar por si mismo, la idea del componente es que la gente pueda hacer uso de él en cualquier situación en la que necesite hacer lo que hace el componente, no obstante, es importante que la gente no tenga que leer 1500 lineas de código de un componente para saber como usarlo, y no es requisito que tenga conocimiento del nivel del autor del componente, por lo que hay que dar una explicación clara y consisa de lo que hace el componente tanto para el usuario como para el interprete de php.
La interface biene a solucionar dicho problema, la idea de la interface es hacer un listado de las funciones y atributos públicos de una clase, de forma que con una lectura rápida se pueda entender las funciones y atributos de un componente, sin tener que leer una cantidad de lineas importantes y comentarios en general, de hecho si es posible, ni siquiera abrir el archivo del componente.
Para que éste modelo sea viable, funcional y práctico, era necesario exigir un punto importante:
En la división Component (la clase principal del componente) NO SE PERMITE NINGÚN TIPO DE COMENTARIO EN EL CÓDIGO, se que a muchos no les gustará ésta medida, pero es imperativo, si no puedes construir un código que se entienda con solo ver la cabecera de la función, los parámetros y una explicación breve, no deberías estar leyendo esto, y deberías buscar un manual de "aprende php desde 0", si bien no se puede comentar absolutamente nada en la clase para que ésta sea válida, es obligatorio que exista una interfaz, y que ésta tenga declaradas todas las funciones y atributos públicos, y que hayan comentarios que, expliquen lo que hace la función, que tipos de datos en los parámetros se espera, qué hace cada parametro, y qué retorna (incluído el tipo de dato que retorna).
Las únicas funciones que quedan de lado son los getters y setters, éstos harán de descriptores de atributos, por lo cual al principio de la interfaz pondrán los setters y getters, explicando si son seteables o no son seteables, de modo que el usuario pueda ver que atributos hay y si se pueden escribir o no.
No debe faltar ninguna función pública en la interface, ni declarar, ni comentar.
un ejemplo de una interfaz correcta:
(primero crearemos el componente de ejemplo)
ComponentMensajesPrivados.php
ahora veremos la interface:
InterfaceMensajesPrivados.php
Luego se continúa con el detallado del resto de las funciones.
En realidad ésta forma de comentar no es necesaria, pero si es necesario que se detallen los tipos de parametros, lo que representa cada parametro, una explicación breve de lo que hace la función y qué es lo que retorna.
Si se decea crear extensiones que tengan sus interfaces, éstas deben estar en el mismo archivo que la extensión del componente.
saludos!
Les recuerdo que como minimo deben tener buenos conocimientos de Programación Orientada a Objetos, sobre le patrón MVC y otras cosas que serán explicadas luego.
Cuando adquieran esos conocimientos podrían empezar a plantearse el desarrollo de un componente.
Hablaremos entonces sobre Components Interface division.
Como dije en una entrada anterior, los componentes se dividen en 3 partes, en ésta entrada explicaremos la segunda división (Interface) y su razón de existir.
ADVERTENCIA: probablemente
mucha gente esté en desacuerdo con lo que expreso en las entradas de mi
blog, la idea del blog siempre fue, como todo blog, la de presentar
textos que muestren un poco de mi "día a día", en mi caso en el mundo de la programación y la informática.
No obstante, todos mis textos están basados en la normativa vigente, y en toda mi experiencia hasta el momento, aquellos que estén en desacuerdo, probablemente sea por ignorancia o desconocimiento, y también podríamos mencionar engreimiento, creer que saben todo, pero tampoco podemos dejar de lado que quizá esté equivocado en algunas cosas, pero con el tiempo me daré cuenta y lo aclararé en nuevas entradas al blog.
No obstante, todos mis textos están basados en la normativa vigente, y en toda mi experiencia hasta el momento, aquellos que estén en desacuerdo, probablemente sea por ignorancia o desconocimiento, y también podríamos mencionar engreimiento, creer que saben todo, pero tampoco podemos dejar de lado que quizá esté equivocado en algunas cosas, pero con el tiempo me daré cuenta y lo aclararé en nuevas entradas al blog.
La razón de la existencia de la interface, es parte de la respuesta a una busqueda que hago hace un tiempo, se dice que el código debe hablar por si mismo, la idea del componente es que la gente pueda hacer uso de él en cualquier situación en la que necesite hacer lo que hace el componente, no obstante, es importante que la gente no tenga que leer 1500 lineas de código de un componente para saber como usarlo, y no es requisito que tenga conocimiento del nivel del autor del componente, por lo que hay que dar una explicación clara y consisa de lo que hace el componente tanto para el usuario como para el interprete de php.
La interface biene a solucionar dicho problema, la idea de la interface es hacer un listado de las funciones y atributos públicos de una clase, de forma que con una lectura rápida se pueda entender las funciones y atributos de un componente, sin tener que leer una cantidad de lineas importantes y comentarios en general, de hecho si es posible, ni siquiera abrir el archivo del componente.
Para que éste modelo sea viable, funcional y práctico, era necesario exigir un punto importante:
En la división Component (la clase principal del componente) NO SE PERMITE NINGÚN TIPO DE COMENTARIO EN EL CÓDIGO, se que a muchos no les gustará ésta medida, pero es imperativo, si no puedes construir un código que se entienda con solo ver la cabecera de la función, los parámetros y una explicación breve, no deberías estar leyendo esto, y deberías buscar un manual de "aprende php desde 0", si bien no se puede comentar absolutamente nada en la clase para que ésta sea válida, es obligatorio que exista una interfaz, y que ésta tenga declaradas todas las funciones y atributos públicos, y que hayan comentarios que, expliquen lo que hace la función, que tipos de datos en los parámetros se espera, qué hace cada parametro, y qué retorna (incluído el tipo de dato que retorna).
Las únicas funciones que quedan de lado son los getters y setters, éstos harán de descriptores de atributos, por lo cual al principio de la interfaz pondrán los setters y getters, explicando si son seteables o no son seteables, de modo que el usuario pueda ver que atributos hay y si se pueden escribir o no.
No debe faltar ninguna función pública en la interface, ni declarar, ni comentar.
un ejemplo de una interfaz correcta:
(primero crearemos el componente de ejemplo)
ComponentMensajesPrivados.php
class ComponentMensajesPrivados implements InterfaceMensajesPrivados
{
use ComLib;
use MyProperty; //opcional, pero si se usa es importante que se encuentre como extension
private $autor = 0;
private $fecha = 0;
private $asunto = null;
private $mensaje = null;
private $visto = false;
public function __construct($autor, $fecha, $asunto, $mensaje, $visto = false)
{
$this->autor = (int) $autor;
$this->fecha = (time) $fecha;
$this->asunto = (string) htmlentities(trim($asunto));
$this->mensaje = (string) htmlentities(trim(nl2br($mensaje)));
$this->visto = $visto;
}
public function ver()
{
$this->visto = true;
return true;
}
public function set_autor($value)
{
$autor = (int) $autor;
$this->autor = ( $auto > 0 ) ? $autor : $this->autor;
}
public function get_autor()
{
return $this->autor;
}
}este ejemplo no tiene todos los setters y getters porque asumo que se darán cuenta que faltan.
ahora veremos la interface:
InterfaceMensajesPrivados.php
interface InterfaceMensajesPrivadosésta interfaz de ejemplo es válida, como verán lo primero que se hace es poner las funciones getters y setters para definir los atributos, las funciones getters y setters SIEMPRE tienen que estar escritas en la clase y en la interface, pero aclarando si realmente esos atributos pueden ser leidos y escritos, o no pueden serlo.
{
// atributos:
public function set_autor($value); // escritura válida
public function get_autor(); // lectura válida
/* Función constructora.
* Setea los valores iniciales de la clase
* (int) $autor: identificador de autor de mensaje
* (int) $fecha: fecha en formato entero (como time(); )
* (string) $asunto: asunto del mensaje
* (string) $mensaje: cuerpo del mensaje
* (bool) $visto: OPCIONAL si el mensaje fué visto o no, por defecto false
* RETURN: instancia de la clase
*/
public function __construct($autor, $fecha, $asunto, $mensaje, $visto);
/* Función ver.
* Setea el atributo ver en true, emulando que el mensaje ya fue visto
* Sin parametros
* RETURN: (bool) si se pudo hacer o no
*/
public function ver();
}
Luego se continúa con el detallado del resto de las funciones.
En realidad ésta forma de comentar no es necesaria, pero si es necesario que se detallen los tipos de parametros, lo que representa cada parametro, una explicación breve de lo que hace la función y qué es lo que retorna.
Si se decea crear extensiones que tengan sus interfaces, éstas deben estar en el mismo archivo que la extensión del componente.
saludos!
0 comentarios:
Publicar un comentario