"No comentes tu código"

Un poco de mi

Sagrario Meneses
Software Architect

@sagmmd

Comentar el código requiere...

MANTENIMIENTO

Los comentarios...

MIENTEN

Los comentarios...

"Permiten compensar nuestra incapacidad para expresarnos en el código"

Preguntemonos

¿Existe una forma de expresar esto en mi código?

Comentarios que debemos evitar

Redundantes

Intención de un valor

De advertencia

Código zombie

Con comentarios

...
    $this->discount($c, $p);
...
 }

 /**
  * Cálculo del descuento de un producto
  *
  * Arreglo con la información de cupón
  * @param array $c
  *
  * Arreglo con la información de producto
  * @param array $p
  */
 protected function discount($c, &$p) {
   //Revisa si el cupón está disponible y no excede el 50%
   if (array_key_exists('n', $c) && $c['d'] < 50) {
      // Guarda el calculo del descuento en la variable del producto
      $p['d'] = ($p['p'] * $c['d']) / 100;
   }
 }

Sin comentarios

const MAX_DISCOUNT = 50;

...
    $this->setAvailableDiscount($coupon, $product);
...    
}

protected function setAvailableDiscount(Coupon $coupon, Product &$product) {
  if (!$coupon->getName()) {
     error_log('Configuración incorrecta de cupón', 3, '/log/error.log');
  
     return; 
  }

  if ($coupon->getDiscount() > self::MAX_DISCOUNT) {
     return;
  }

  $discountInCents = $product->getPrice() * $coupon->getDiscount();
  $product->setDiscount($discountInCents / 100);
}

const MAX_DISCOUNT = 50;

...
    $this->setAvailableDiscount($coupon, $product);
...    
}

protected function setAvailableDiscount(Coupon $coupon, Product &$product) {
  if (!$coupon->getName()) {
     error_log('Configuración incorrecta de cupón', 3, '/log/error.log');
  
     return; 
  }

  if ($coupon->getDiscount() > self::MAX_DISCOUNT) {
     return;
  }

  $discountInCents = $product->getPrice() * $coupon->getDiscount();
  $product->setDiscount($discountInCents / 100);
}

...
    $this->discount($c, $p);
...
 }

 /**
  * Cálculo del descuento de un producto
  *
  * Arreglo con la información de cupón
  * @param array $c
  *
  * Arreglo con la información de producto
  * @param array $p
  */
 protected function discount($c, &$p) {
   //Revisa si el cupón está disponible y no excede el 50%
   if (array_key_exists('n', $c) && $c['d'] < 50) {
      // Guarda el calculo del descuento en la variable del producto
      $p['d'] = ($p['p'] * $c['d']) / 100;
   }
 }

Redundancia

class Product
{
    /**
     * @var float
     */
    private $price;

    /**
     * @param float $price
     */
    public function setPrice($price): void
    {
        $this->price = $price;
    }
}

class Product
{
    private float $price;

    public function setPrice(float $price): void
    {
        $this->price = $price;
    }
}

Comentarios confusos

protected function productDiscount($c, &$p) {
   //Revisa si el cupón está disponible y no excede el 50%
   if (array_key_exists('n', $c) && $c['d'] < 30) {
      // Guarda el cálculo del descuento en la variable del producto
      $p['d'] = ($p['p'] * $c['d']) / 100;
   }
}

Comentarios de advertencia

protected function setAvailableDiscount(Coupon $coupon, Product &$product) {

  // OJO: Siempre siempre validar el nombre, porque si no hay nombre
  // quiere decir que es un cupón que aún no se lanza a campaña.
  if (!$coupon->getName()) {
     return; 
  }
  
  $discountInCents = $product->getPrice() * $coupon->getDiscount();
  $product->setDiscount($discountInCents / 100);
}

Código zombie

protected function setAvailableDiscount(Coupon $coupon, Product &$product) {
  if (!$coupon->getName()) {
     //error_log('Configuración incorrecta de cupón', 3, '/log/error.log');
  
     return; 
  }

  /*if ($coupon->getDiscount() > self::MAX_DISCOUNT) {
     return;
  }*/

  $discountInCents = $product->getPrice() * $coupon->getDiscount();
  $product->setDiscount($discountInCents / 100);
}

Entonces ¿NO hay comentarios buenos?

Comentarios válidos

TODO

protected function setAvailableDiscount(Product &$product) { 
   $now = new DateTime("now");

   if ($this->coupon->getExpirationDate() > $now) {
     // TODO: Lanzar una excepción que informe al usuario este 
     // caso cuando el frontend este listo en la versión 1.4.
     return;
   }

   $discountInCents = $product->getPrice() * $this->coupon->getDiscount();
   $product->setDiscount($discountInCents / 100);
}