Otra de esas posibilidades de las que hablamos es realizar el respaldo con PHP, lo que nos permitirá hacerlo con casi todos los hostings, además de que es fácilmente automatizable. La principal desventaja, por contra, es que es una opción algo más laboriosa, pues tendremos que programar el script. Pero como la rueda casi siempre está inventada, en internet tienes muchas soluciones que te facilitarán la labor.

MySQL BackUp Lite

Yo os propongo esta sencilla solución que he desarrollado, de la que os dejo el código a continuación. En cualquier momento puedes acceder a la versión más actualizada de MySQL Backup Lite en Github.

/**
*
* MySql Backup Lite Class
*
* @author     Andres Hierro
* @copyright  2019 Andres Hierro
* @license    http://www.apache.org/licenses/LICENSE-2.0  Apache License, Version 2.0
* @version    0.0.1
* @link       http://ahierro.es/
*
*
*
* Copyright 2019 Andrés Hierro
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
*     http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
*/

class MySqlBackupLite {

  private $host;
  private $user;
  private $pass;
  private $name;

  private $fileName = "mySqlBackup.sql";
  private $fileDir = "./";
  private $fileCompression = false;

  private $timeZone = '+00:00';

  private $mySqli;
  private $sqlString = "";
  private $arrayTables;

  private $tableFieldCount = 0;
  private $tableNumberOfRows = 0;
  private $queryResult;



  public function __construct(array $arrayConnConfig) {

      if (
        (!isset($arrayConnConfig['host'])) ||
        (!isset($arrayConnConfig['user'])) ||
        (!isset($arrayConnConfig['pass'])) ||
        (!isset($arrayConnConfig['name']))
      ) {
          throw new Exception('Missing connection data.');

      }
      $this->setHost($arrayConnConfig['host']);
      $this->setUser($arrayConnConfig['user']);
      $this->setPass($arrayConnConfig['pass']);
      $this->setName($arrayConnConfig['name']);

  }



  public function backUp() {

    $this->connectMySql();
    $this->getTables();
    $this->generateSqlHeader();
    $this->createTableStaments();
    $this->insertStaments();
    $this->generateSqlFooter();

  }



  private function setHost($host) {
    $this->host = $host;
  }



  private function setUser($user) {
    $this->user = $user;
  }



  private function setPass($password) {
    $this->pass = $password;
  }



  private function setName($name) {
    $this->name = $name;
  }



  public function setFileName($name) {
    $this->fileName = $name;
  }



  public function setFileDir($dir) {
    $this->fileDir = $dir;
  }



  public function setFileCompression($compression) {
    $this->fileCompression = $compression;
  }



  private function connectMySql() {

    $this->mySqli = new mysqli($this->host, $this->user, $this->pass, $this->name);
    $this->mySqli->select_db($this->name);
    $this->mySqli->query("SET NAMES 'utf8'");

  }



  private function getTables() {

    $queryTables = $this->mySqli->query('SHOW TABLES');
    while($row = $queryTables->fetch_row()) {
      $this->arrayTables[] = $row[0];
    }

  }



  private function generateSqlHeader() {

    $this->sqlString  = 'SET SQL_MODE = "NO_AUTO_VALUE_ON_ZERO";' . "\r\n";
    $this->sqlString .= 'SET time_zone = "' . $this->timeZone . '";' . "\r\n\r\n\r\n";
    $this->sqlString .= '/*!40101 SET @OLD_CHARACTER_SET_CLIENT=@@CHARACTER_SET_CLIENT */;' . "\r\n";
    $this->sqlString .= '/*!40101 SET @OLD_CHARACTER_SET_RESULTS=@@CHARACTER_SET_RESULTS */;' . "\r\n";
    $this->sqlString .= '/*!40101 SET @OLD_COLLATION_CONNECTION=@@COLLATION_CONNECTION */;' . "\r\n";
    $this->sqlString .= '/*!40101 SET NAMES utf8 */;' . "\r\n";
    $this->sqlString .= '--' . "\r\n";
    $this->sqlString .= '-- Database: `' . $this->name . '`' . "\r\n";
    $this->sqlString .= '--' . "\r\n\r\n\r\n";

    return;

  }



  private function createTableStaments() {

    foreach($this->arrayTables as $table){
      $this->sqlCreateTableStament($table);
    }

  }



  private function sqlCreateTableStament($table) {

    $res = $this->mySqli->query('SHOW CREATE TABLE '.$table);
    $temp = $res->fetch_row();
		$this->sqlString .= "\n\n" . str_ireplace('CREATE TABLE `','CREATE TABLE IF NOT EXISTS `', $temp[1]) . ";\n\n";

  }



  private function insertStaments() {

    foreach($this->arrayTables as $table){
      $this->sqlInsertStaments($table);
    }

  }



  private function sqlInsertStaments($table) {

		$this->getTableData($table);

    if($this->tableFieldCount == 0) {
      return;
    }


    $i = 0;
		while($row = $this->queryResult->fetch_row())	{

      $this->insertResultHeader($table, $i);
      $this->insertSingleResult($row);

      $i++;
      $this->sqlString .= (($i != 0) && ($i % 100 == 0) || ($i == $this->tableNumberOfRows)) ? ";" : ",";

		}

    $this->sqlString .= "\n\n\n";

  }



  private function getTableData($table) {

  	$this->queryResult	= $this->mySqli->query('SELECT * FROM `' . $table . '`');
    $this->tableFieldCount = $this->queryResult->field_count;
    $this->tableNumberOfRows = $this->mySqli->affected_rows;

  }



  private function insertResultHeader($table, $currentRowNumber) {

  	if ($currentRowNumber % 100 == 0 || $currentRowNumber == 0 )	{
      $this->sqlString .= "\nINSERT INTO " . $table . " VALUES";
    }

  }



  private function insertSingleResult($row) {

    $this->sqlString .= "\n(";

    for($i = 0; $i < $this->tableFieldCount; $i++){

      $row[$i] = str_replace("\n","\\n", addslashes($row[$i]));

      $this->sqlString .= (isset($row[$i])) ? '"'.$row[$i].'"' : '""';
      if($i < ($this->tableFieldCount-1)){
        $this->sqlString.= ',';
      }

    }

    $this->sqlString .=")";

  }



  private function generateSqlFooter() {

    $this->sqlString .=  "\r\n\r\n";
    $this->sqlString .=  '/*!40101 SET CHARACTER_SET_CLIENT=@OLD_CHARACTER_SET_CLIENT */;';
    $this->sqlString .=  "\r\n";
    $this->sqlString .=  '/*!40101 SET CHARACTER_SET_RESULTS=@OLD_CHARACTER_SET_RESULTS */;';
    $this->sqlString .=  "\r\n";
    $this->sqlString .=  '/*!40101 SET COLLATION_CONNECTION=@OLD_COLLATION_CONNECTION */;';

  }



  public function downloadFile() {

      ob_get_clean();
      header('Content-Type: application/octet-stream');
      header("Content-Transfer-Encoding: Binary");
      header('Content-Length: '. (function_exists('mb_strlen') ? mb_strlen($this->sqlString, '8bit'): strlen($this->sqlString)) );
      header("Content-disposition: attachment; filename=\"".$this->fileName."\"");
    	echo $this->sqlString; exit;

  }



  public function saveToFile() {

    if (!$backupFile = fopen($this->fileDir . $this->fileName, "w+")) {
        throw new Exception('Imposible to create file.');
    }
    fwrite($backupFile, $this->sqlString);
    fclose($backupFile);

  }


}

Realizar la copia de seguridad

La solución propuesta nos proporciona dos opciones que podemos utilizar según nuestras necesidades:

1. Realizar el backup y descargarlo.
2. Realizar el backup y guardarlo en un archivo.

En ambos casos incluimos la clase y le pasaremos al método constructor los datos de la conexión a la base de datos en un array como el que ves a continuación:

include('MySqlBackup.php');

$arrayDbConf['host'] = 'dbHost';
$arrayDbConf['user'] = 'dbUser';
$arrayDbConf['pass'] = 'dbPassword';
$arrayDbConf['name'] = 'dbName';

Respaldar y descargar

Para realizar el backup y descargarlo serán suficientes unas pocas líneas:

try {

  $bck = new MySqlBackupLite($arrayDbConf);
  $bck->backUp();
  $bck->downloadFile();

}
catch(Exception $e) {

  echo $e;

}

Respaldar y guardar en un archivo

Para guardar el resultado en un archivo además deberemos de indicarle el nombre del archivo y el directorio dónde guardarlo.

try {

  $bck = new MySqlBackupLite($arrayDbConf);
  $bck->backUp();
  $bck->setFileDir('./backups/');
  $bck->setFileName('backupFileNae.sql');
  $bck->saveToFile();

}
catch(Exception $e) {

  echo $e;

}

Solo una parte del proceso

Pero en muchas situaciones, este respaldo sera solo una parte del proceso. Nosotros hemos propuesto un escenario mayor en el que clonamos nuestra web en un servidor local, en breve publicaremos el artículo.

Créditos y rerefencias

• Imagen principal: Tumisu en Pixabay.
• Solución Mysql Backup Lite: Andrés Hierro, github.

La elección de los nombres de los distintos elementos que intervienen en la programación es una de esas tareas que si bien no es técnicamente compleja, puede suponer un antes y un después en cuanto a la calidad del código que generamos.

En esta entrada veremos cómo la elección de nombres adecuados puede contribuir a reducir el número de comentarios necesarios en el código fuente, y por lo tanto a mejorar su limpieza, comprensión y mantenimiento.

Este artículo es el cuarto de una serie de entradas dedicados a los comentarios y cuyo índice podemos encontrar en la entrada Introducción a los comentarios en programación. Así que si estás interesado en mejorar no solo tus comentarios, si no tu programación en general, te recomiendo que leas los tres anteriores: Introducción a los comentarios en programación, Comentarios a evitar al programar, y Mantenimiento de comentarios en la programación.

Nombres descriptivos

Es  bastante común ver funciones o métodos precedidos de un comentario que explica cual es su cometido. Esta situación por si misma no es mala siempre que ayude a entender el código a otros desarrolladores. Sin embargo, en muchas ocasiones la elección de un nombre adecuado puede ser suficientemente descriptiva como para evitar el comentario.

Veamos un ejemplo inspirado en una aplicación TPV (Terminal Punto de Venta):

// Devuelve el precio de un producto valorando descuentos y
// rebajas para un cliente autentificado
private bool getPrice(int itemId, int userId) {
{
   ...
}

Como vemos el nombre del método es descriptivo hasta cierto punto, motivo por el que el comentario ayuda a complementarlo. Pero esto mismo podríamos hacerlo utilizando un nombre más adecuado:

private bool getAuthentificatedCustomerFinalPrice(int itemId, int userId) {
{
   ...
}

En este segundo ejemplo al leer el nombre del método sabemos exactamente que esperar de él, así que no es necesario el comentario.

Hemos podido utilizar esta técnica sin ningún problema porque cumplimos la regla que establece que cada función debe hacer una única cosa. Si no la cumplimos e intentamos escoger un nombre descriptivo nos encontraremos con nombres excesivamente largos. Veamos un ejemplo siguiendo el hilo anterior pero en esta ocasión el método realizará dos tareas:

private bool identifyIfCustomerIsLoggedAngGetFinalPrice(int itemId, int userId) {
{
   ...
}

Cuantas más cosas haga el método, más largo y difícil de elegir será el nombre y esto se traducirá en un código poco legible y difícil de trabajar, volviendo a ser necesarios los comentarios.

Y por supuesto que esta técnica es totalmente aplicable a variables y constantes, escogiendo nombre adecuados eliminaremos la necesidad de explicar el objetivo de las mismas con comentarios. No es lo mismo usar nombres poco descriptivos y acompañarlos de un comentario en la declaración:

// Coste de reposición de artículo
private float cost;

Que utilizar nombre descriptivos, prescindir de los comentarios y saber que contiene exactamente la variable en cualquier punto del programa:

private float supplierPriceOfList;

Sustituir un pedazo código por una función

En ocasiones explicamos pedazos de código porque queremos transmitir nuestra intención, porque ayuda a la comprensión de un algoritmo con cierta complejidad, porque nos parece que es engorroso de leer y un comentario lo facilitaría, etc. Pongamos un ejemplo muy sencillo, de nuevo sobre un programa TPV:

// Comprobamos si hemos introducido un descuento manual 
if(
   (item.price  > item.proposedPrice)  &&
   (discount.reason is null) &&
   (item.price != item.proposedPrice * customer.discount)
)
{ 
   ... 
}

El programador que ha escrito este código (yo) ha querido dejar claro que las tres condiciones que ha escrito tenían como intención averiguar si se había introducido un descuento manual.

Pero quizás sea mucho más claro leer el código de esta manera:

if(manualDiscountIsApplyed())  
{
   ...  
}

Y para ello solo tenemos que encapsular ese bloque lógico en otro método con un nombre adecuado:

private bool manualDiscountIsApplyed()  
{  
   bool discountIsApplied = false;  
   if(  
      (item.price > item.proposedPrice) &&
      (discount.reason is null) &&
      (item.price != item.proposedPrice * customer.discount)  
   )  
   {  
      discountIsApplied = true;  
   }  
   return discountIsApplied;  
}  

Aunque si lo pensamos un instante lo único que hemos hecho ha sido un uso correcto de la programación orientada a objetos, el resto ha sido de nuevo la elección de un buen nombre.

Conclusión

En el desarrollo de software, como en prácticamente todo, cuanto más simple y breve sea la solución, mejor. Lejos de de extender y adornar el código debemos procurar sintetizar y aclarar todo lo posible de forma que sea sencillo de comprender por si mismo, y para ello una elección correcta de nombres es fundamental.

Y como es habitual, sería muy interesante conocer tu punto de vista, ¿qué otra técnica utilizas tú para mejorar la legibilidad del código y evitar comentarios innecesarios? Comparte tu experiencia en un comentario.

En multitud ocasiones he visto y he escrito comentarios que ensucian el código y que en el mejor de los casos solo son una molestia visual. En cambio, otras ocasiones, me he tropezado con comentarios que pueden llegar a confundir al programador, sembrar la duda en él o hacer que gaste más tiempo del necesario intentando comprender la discrepancia entre el comentario y el código.

Esto ocurre principalmente porque al igual que sucede con el resto del código fuente, los comentarios requieren de un mantenimiento. Y para conseguirlo es necesario que el desarrollador sea mucho más estricto que con el resto del código: si el compilador no alerta tendremos que ser nosotros quien garanticemos que son correctos. Y el problema radica en que incluso si los comentarios son un verdadero desastre, si el código es correcto el programa funcionará, y muchas veces eso nos basta.

[the_ad id=»1018″]

Así que en esta entrada trataremos algunos aspectos que hemos de tener en cuenta a la hora de mantener nuestros comentarios. Este artículo pertenece a una serie cuyo índice podemos encontrar en la entrada Introducción a los comentarios en programación.

Comentarios a evitar

Hace una semana publicamos una entrada titulada Comentarios a evitar al programar.  En ella hablábamos de los comentarios que no deberíamos hacer que perduren en el código, y podemos decir que éste es el primer paso que debemos de tomar a la hora de mantener los comentarios. Haciendo un breve resumen hablamos de:

1. Código fuente comentado
2. Identificación de modificaciones
3. Código para debugar
4. ToDos y notas de tareas pendientes

Si todavía no has leído este artículo te recomiendo que lo hagas antes de continuar con el siguiente punto.

Copy & Paste

¿Cuantas veces has copiado y pegado un fragmento de código en el que existen comentarios? Pongamos el ejemplo de un método cualquiera, queremos crear otro bastante similar  y optamos por copiar y pegar en lugar de escribir desde cero. Acto seguido modificamos el nuevo método, pero, ¿cuantas veces hemos dejado un comentario sin modificar haciendo referencia al funcionamiento del método original?

Como primer planteamiento me preguntaría si el comentario es realmente necesario, pues si no le has dado la importancia adecuada quizás es simplemente porque no la necesita y puede ser eliminado. Pero en caso de que deba ser mantenido no olvides actualizarlo si es necesario. De lo contrario estarás mintiendo al programador que lo lea.

Modificaciones en el código

Lo más habitual cuando modificamos unos fuentes es que estemos alterando de una u otra manera su funcionamiento. Si existe un comentario realizado sobre el bloque de código que estamos modificando, deberemos de verificar que tras la modificación el comentario sigue siendo tan necesario y válido como era antes de cambiar una sola línea. De lo contrario volveríamos a tener un comentario erróneo.

Imaginemos que tenemos un método userIsAuthenticated() que devuelve la ID de un usuario en caso de que esté autentificado y 0 en caso de que no lo esté.  Imaginemos que modificamos ese método para que devuelva true si está autentificado y false si no lo está, y a su vez creamos otro método getUserId() que devuelve la ID de un usuario autentificado. En caso de que existiera algún comentario en el método original o en alguna llamada al método también debemos de modificarlo para que refleje el nuevo comportamiento.

El precio de no mantener los comentarios

Imaginemos qué estamos revisando un código escrito por otro desarrollador, y a medida que avanzamos notamos que los comentarios son superfluos y en muchos casos imprecisos e incoherentes con respecto al código, ¿qué ocurriría? Probablemente o los ignoraríamos por completo o seguiríamos leyéndolos a regañadientes.

Pero ¿que ocurriría si en lugar de ignorarlos tomamos por bueno la información de los comentarios en lugar de la realidad del código? La respuesta dependerá de cada situación, y en cada una de ellas intervendrán muchos factores, así que dejo esta respuesta a tu criterio, pero personalmente ninguna situación de las que soy capaz de imaginar es positiva.

Refactorizar comentarios

Hace no mucho escribíamos también sobre el código oloroso en la entrada ¿A qué huele el código fuente? y sobre refactorización en la entrada Refactorización de código.

La refactorización de los comentarios, que hoy estamos llamando mantenimiento, es tan importante como la del propio código. No basta solo con seguir los manuales de buenas prácticas al escribir nuevo código, debemos limpiar y corregir los comentarios irrelevantes, incomprensibles, imprecisos, incoherentes o erróneos que nos encontremos como parte de nuestra labor.

Si decidimos no refactorizar la primera consecuencia será que asumiremos que tanto nosotros como el resto del equipo que trabaje con ese código vamos a tener que convivir con comentarios erróneos. Y la segunda consecuencia que se dará con bastante probabilidad, es que el equipo se contagiará de la dejadez del código y comenzará a emplear malas prácticas, lo que suele acabar en un problema que crece con el paso del tiempo.

Conclusión

Debemos tratar los comentarios con la misma delicadeza que tratamos el resto del código, pues un código bien comentado facilita el mantenimiento del software y contribuye a evitar la deuda tecnológica.

¿Y tu qué opinas?, ¿crees que existen más situaciones relacionadas con los comentarios que debamos tener en cuenta en el mantenimiento?, ¿tienes algún consejo o recomendación? Sabes que nos gusta leer tu opinión, compártela en los comentarios.

Por supuesto que podemos utilizarlos para ayudarnos a debugar,  para ponernos notas, recordatorios o ToDos en en código y mil usos más. Pero los comentarios tienen un único objetivo que es aclarar la intención de un determinado bloque de código, y deberemos ceñirnos a este objetivo para garantizar la limpieza y la mantenibilidad de nuestros fuentes. Todo uso que se aleje de este objetivo (o de la documentación del código) no debe perdurar en el tiempo.

Así que a continuación veremos algunos usos inadecuados de los comentarios que están muy extendidos y que deberíamos evitar.

Este artículo forma parte de una serie que trata de una forma más amplia el uso de los comentarios en la programación, y en la que el artículo Introducción a los comentarios en la programación utilizaremos como índice.

Código comentado

Cuando estamos trabajando en un proyecto es bastante habitual encontrarnos con código fuente comentado. Suele ocurrir que comentemos  un pedazo de código por un motivo temporal y no realicemos una limpieza posterior, con lo que queda ahí para la posteridad. Otro motivo bastante habitual es que realicemos un cambio en el código, no dispongamos de un software de control de versiones y no queramos perder el código original.

Sea cual sea el motivo, ¿qué debe interpretar un desarrollador cuando se encuentra un código comentado? ¿Lo ignora? ¿Lo compara o lo interpreta e intenta relacionarlo con el código no comentado? ¿Qué se supone que debe hacer?

Debemos ser limpios y no dejarnos fragmentos de códigos comentados en nuestros fuentes, y si no disponemos de un software de control de versiones deberíamos darle la máxima prioridad a incluir uno en nuestro proyecto. Puedes ver las entradas Instalar y configurar Git en una Raspberry Pi con Ubuntu Mate o Crear un repositorio remoto en Git desde archivos locales.

Identificación de modificaciones

Un uso menos extendido pero con el que he tropezado en alguna ocasión es una versión «sofisticada» del punto anterior. Realizamos una modificación, comentamos el código original e incluimos ciertos datos como el nombre del desarrollador, la fecha en la que se realizó el cambio y el motivo por el que se hizo.

Veamos el siguiente ejemplos:

// J.J. 15/10/2017  
// Bug: no permitía nombres de 8 caracteres  
// if($userName > 8) {  
if($userName >= 8) {  
   ...  
}

La molestia visual es evidente, además que que nos llevará más tiempo leer y comprender 4 líneas que una:

if($userName >= 8) { 
   ... 
}

Siempre existen circunstancias alrededor de un proyecto, pero de nuevo, si éste no tiene software de control de versiones todos nuestros esfuerzos deberían centrarse en conseguirlo.

Código para debugar

Esto ocurre en mayor medida, aunque no exclusivamente, en proyectos de desarrollo web. Para ayudarnos a debugar nuestro software incluimos líneas extra de códigos que realizan una tarea determinada. Una vez completado el debug las comentamos y permanecen como partes del código fuente eternamente. Esto no hace más que ensuciar el código, la persona que vuelva a tocar esos fuentes probablemente no necesitará debugar en ese punto, o lo hará de otra forma, así que seamos limpios y borremos este tipo de comentarios.

Además, otro hecho que ocurre, es que si continuamente encontramos comentarios que no añaden valor, acabaremos por ignorarlos todos, ¿por qué tenemos que tropezarnos con comentarios de este tipo en el código?

/*  
echo '<pre>';  
printr($var);
echo '</pre>';  
die();  
*/  

Pero sobre todo, asegúrate de disponer de herramientas para debug. Cuando programamos en Java, C++, Basic, C#, etc. no concebimos desarrollar sin herramientas de debug adecuadas, que por lo general vienen incluidas en las IDEs.  Así que si eres desarrollador web, asegúrate también de disponer de éstas herramientas. En este mismo blog tenemos una entrada sobre cómo Debugar PHP con Netbeans y XCode. Para debugar Javascript también tienes múltiples opciones con herramientas como Chrome DevTools o la consola de Mozilla Firefox.

ToDos y notas de trabajo

En ocasiones nos ponemos notas al programar, yo por ejemplo en ciertas situaciones  incluyo alguna línea del tipo:

// todo: añadir validación de longitud máxima al nombre  
if($userName >= 8) {  
...
}

Existen IDEs que traen soluciones para este tipo de notas, también existen programas que pueden ayudarnos a gestionar estas notas de forma muy efectiva. De cualquier forma, si te gusta trabajar con este tipo de comentarios asegúrate de borrarlo una vez que hayas finalizado la tarea, y si no la vas a terminar, el código fuente no es el lugar dónde indicar las tareas pendientes de completar, así que mejor busca una alternativa.

Concluisión

A pesar de que los comentarios lo aguantan todo, debemos de ser estrictos y hacer un buen uso de ellos, o de lo contrario nunca tendremos un código limpio. Como hemos podido ver, con un software de control de versiones y  alguna herramienta para gestionar tareas pendientes podemos reducir drásticamente el número de comentarios inadecuados.

Seguro que tú también te has encontrado con muchos tipos de comentarios inadecuados, ¿de qué tipo eran? ¿qué herramientas utilizas para evitar estos comentarios?  Como siempre me gustaría conocer tu experiencia.

A pesar de que en un primer instante pueda parecer un asunto un tanto superficial, los comentarios en la programación son un tema muy interesante, no por su complejidad, sino porque un correcto uso de ellos puede marcar la diferencia en cuanto a limpieza, facilidad de comprensión del código y su mantenimiento.

Objetivo de los comentarios

Los comentarios, cuando hablamos de programación, son bloques de texto escritos en lenguaje natural que están incluidos dentro del código fuente, que el compilador ignora y que por norma general están destinados a que sea el programador el que los interprete.

El objetivo principal de un comentario es dejar constancia en el código fuente de la intención de un determinado bloque de código. Esto es especialmente útil cuando más de un programador tiene acceso al mismo código o para recordar en el futuro por qué tomamos determinada estrategia para el código al que hacemos referencia.

[the_ad id=»1018″]

Existe también un segundo objetivo muy extendido y de gran utilidad que es para documentar el código. Siguiendo algunas reglas que varían en función de la herramienta, ciertos comentarios pueden ser interpretados por aplicaciones que generan documentación de manera automática. Algunos ejemplos de estas aplicaciones son Javadoc en Java o Doxygen en PHP.

Características de los comentarios

Así que dejando al margen del tema de la documentación, para que un comentario aporte todo el valor que se le presupone debe cumplir algunas características.

1. Complementar al código. Un buen comentario debe transmitir la intención del programador, el concepto, el motivo, la estrategia, pero nunca traducir a lenguaje natural ni explicar el código que hemos escrito, eso ya lo sabe hacer la persona que lee el código.
2. Ser claro y comprensible. Escribimos los comentarios para que otros, o nosotros mismos en el futuro, los lean, así que asegurémonos de que cuando lo hagan comprendan perfectamente el mensaje que les estamos transmitiendo. ¿Cuántas veces escribiste una nota que al leerla pasado cierto tiempo no eres capaz de entenderla?
3. Ser conciso. No hace falta extendernos o explicar hasta el último detalle, cuanto más concisos seamos más fácil será comprenderlo e invertiremos menos tiempo en ello.

Profundizando en los comentarios

Realmente esta entrada no era más que una excusa para introducir y dar paso a otros artículos relacionados con los comentarios.

Estos artículos guardarán también cierta relación con una entrada que escribimos hace tan solo unas semanas atrás: ¿A qué huele el código fuente?, tratando el código oloroso y en la que hacíamos referencia a los comentarios como una posible fuente de olores.

Así que a continuación tenéis todas esas entradas que durante las próximas semanas iremos publicando:

1. Comentarios a evitar
2. Mantenimiento de comentarios
3. Comentarios y nombres de elementos

Conclusión

Los comentarios, lejos de lo que pueda parecer cuando no se tiene la suficiente experiencia, son un tema que a pesar de su simplicidad pueden marcar la diferencia en nuestro código y al que merece la pena dedicarle cierto tiempo.

Por otro lado, en función de diferentes factores relacionados con un proyecto de desarrollo podemos trabajar en equipo, que es lo más probable, o solos. Cuando trabajamos en equipo es lógico que el software de control de versiones se encuentre en un servidor centralizado. Cuando trabajamos solos podemos decidir que solo esté en nuestra máquina.

Personalmente incluso trabajando en solitario en un proyecto me gusta versionar contra en un servidor centralizado por dos motivos principales:

1. Mayor seguridad ante una eventualidad en mi equipo local, circunstancia que no evita que el proyecto deba estar respaldado por copias de seguridad.
2. Posibilidad de trabajar en múltiples dispositivos, una opción más o menos interesante en función de nuestras circunstancias.

En caso de que el proyecto que tengamos entre manos sea de ámbito personal, es más que razonable pensar que no todos disponemos de un servidor en casa dónce centralizar el versionado. Esta situación la podemos resolver con un viejo pc, o si no disponemos de uno con una Raspberry Pi que haga las veces de servidor. Aquí te dejo un enlace al artículo Instalar y configurar Git en una Raspberry PI con Ubuntu Mate, por si quieres probarlo.

Así que vamos al lío y para ello asumiremos que nuestro servidor está configurado con la ip 192.168.1.10 y el nombre de nuestro usuario es usuario.

Creamos nuestro repositorio remoto

Lo primero que debemos hacer es crear y configurar correctamente un repositorio vacío en la máquina remota, así que empezaremos por conectarnos a ella:

ssh usuario@192.168.1.10

Ya en la consola remota creamos el directorio dónde alojaremos el repositorio que vamos a crear, personalmente creo un directorio en el que incluyo todos los repositorios:

cd ~
mkdir gitRepositoryRoot
cd gitRepositoryRoot
mkdir nuevoProyecto
cd nuevoProyecto

Y por fin creamos nuestro repositorio vacío y lo configuramos:

git --bare init
git config core.sharedrepository 1
git config receive.denyNonFastforwards true
git config --bool core.bare true

El último paso en la máquina remota es asignar los permisos adecuados al repositorio:

find objects -type d -exec chmod 02770 {} \;

Creamos nuestro repositorio local

Una vez que nuestro repositorio está correctamente creado en el servidor deberemos crear un repositorio local a partir de los fuentes que ya tenemos para posteriormente enlazarlo y enviarlo al repositorio que previamente hemos creado en la máquina remota.

Creamos el repositorio local y añadimos los fuentes existentes que supondremos que se encuentran en /var/www/nuevoProyecto:

cd /var/www/nuevoProyecto
git init
git add *
git commit -m "Commit inicial"

Creamos el repositorio y añadimos los fuentes:

git remote add origin ssh://usuario@192.168.1.10/home/usuario/gitRepositoryRoot/nuevoProyecto
git push -u origin master

Comprobamos que todo ha salido bien

Por último comprobaremos que hemos realizado el proceso correctamente y todo funciona correctamente.

git checkout origin/master
git branch -f master origin/master
git checkout master

Conclusión

Trabajemos en grupo o en solitario versionar nuestro código en una máquina remota es una tarea sencilla que aporta grandes beneficios. Cómo siempre me gustaría saber cómo lo haces tú, qué haces distinto, si este artículo te ha ayudado… Si te animas a compartir deja un comentario.

Pues bien, si te gusta trastear tanto como a mi y quieres pasar un buen rato, si tienes un pequeño proyecto personal que quieres «profesionalizar» con un servidor de pruebas, si necesitas un servidor de control de versiones, etc. Una Raspberry PI es una solución muy económica y 100% válida siempre y cuando tus necesidades de hardware no son excesivas y la criticidad de tu proyecto lo permite.

Así que dedicaremos varios artículos a instalar y configurar diversos servidores en una Raspberry Pi para mejorar y complementar nuestro entorno de desarrollo personal.

Para esta serie de entradas utilizo una Raspberry PI 3 Model B sobre la que corre un sistema operativo Ubuntu Mate 16.0.4.2. Todo lo que aquí veremos podemos hacerlo con Raspbian aunque es posible que existan ciertas diferencias en las rutas de algunos archivos u otros pequeños detalles.

Así que vamos al grano y veamos que vamos a hacer con este SBC:

1. Habilitar el acceso mediante SSH
2. Instalar y configurar un servidor de control de versionado de software, en este caso GIT.
3. Instalar y configurar un servidor LAMP.
4. Crear nuestro primer repositorio remoto en Git.
5. Crear nuestro primer entorno en Laravel.
6. Instalar y configurar un servidor de FTP.
7. Configurar un entorno de integración continua.

Si no dispones de una Raspberry pero si de un viejo pc o de otro u otro mini pc el contenido de esta serie de entradas te servirá de igual manera.

Si echas en falta algo en este servidor para proyectos personales que ayude al desarrollo de un proyecto déjalo en los comentarios.

Por otro lado, es increíble la cantidad de desarrolladores para los que si bien en otros lenguajes utilizar un programa para debugar forma parte de su día a día, cuando programan en php lo hacen de una forma un tanto rudimentaria valiéndose de funciones cómo echo(), print_f(), die()  u otras que les ayuden a mostrar en el navegador lo que deberían ver en la herramienta de debug.

Lo reconozco, yo también lo he hecho durante largos periodos de tiempo, y por ese motivo conozco de primera mano la gran diferencia que existe entre utilizar una herramienta adecuada o no hacerlo. Lo peor de todo es que solucionar esta situación es muy sencillo, y basta con un poco de disciplina y 15 minutos de configuración.

Aprovechando que tengo un entorno de desarrollo relativamente nuevo, vamos a ver como se configura. El software que utilizo es:

• Ubuntu 18.04.1 LTS
• Apache 2.4.29
• PHP 7.2.10
• NetBeans 8.2
• Mozilla Firefox

Vamos a dar por hecho que ya tenemos este software instalado y nos centraremos en instalar y configurar XDebug.

Configuración del servidor

El primer paso es comprobar si tenemos XDebug instalado, por defecto no suele ser así. Esta comprobación la podemos hacer mediante phpinfo(). Si no está instalado lo instalamos:

sudo apt-get install php-xdebug

Buscamos el archivo de configuración de la extensión, en mi caso /etc/php/7.2/apache2/conf.d/20-xdebug.ini. Lo editamos:

sudo vim /etc/php/7.2/apache2/conf.d/20-xdebug.ini

El archivo debería quedar así:

zend_extension=xdebug.so
xdebug.profiler_enable = On
xdebug.remote_enable=On
xdebug.remote_host="localhost"
xdebug.remote_port=9000
xdebug.remote_handler="dbgp"

La primera línea que habilita la extensión de php ya deberíais tenerla, así que solo tendríamos que agregar el resto. Prestad especial atención al puerto, pues tendrá que coincidir con el que especifiquemos en NetBeans.

Ya sólo nos queda reiniciar Apache y pasaremos a configurar NetBeans:

sudo service apache2 restart

Configuración de NetBeans

Ya casi estamos. Abrimos la configuración de NetBeans mediante los menús «Tools» -> «Options». Accedemos a la configuración de PHP y en la pestaña «Debugging» nos aseguramos de que hemos especifiaco el mismo puerto que en la configuración de XDebug para PHP, en nuestro caso el puerto 9000.

Guardamos la configuración, salimos y con esto ya tenemos toda la configuración relativa a XDebug hecha.

La última configuración necesaria para poder debugar se realiza en la configuración de cada proyecto de Netbeans. Para acceder a ella debemos tener visible la ventana de proyectos, botón derecho sobre el propio proyecto y seleccionamos la opción «Properties»del menú.

En la venta de configuración, accederemos al menú «Run Configuration» y nos aseguraremos que los campos «Project URL» y «Index File» están correctamente configurados.

Conclusión

Una configuración muy sencilla que nos ahorrará muchos quebraderos de cabeza. ¿Y tú cómo debugas cuando programas en PHP?