Un contrato funcional y descriptivo es mucho mejor que uno que solo funciona y no entienden porqué.

En el mundo blockchain, una vez que realizamos una transacción, ésta queda grabada a fuego en la red. No podemos modificarla de ninguna manera. Si bien esto evita cientos de problemas de seguridad y nos garantiza que los datos siempre sean los mismos, a la hora de crear código y documentarlo nos obliga a que el mismo sea lo más descriptivo posible.

Cuando uno quiere realizar un cambio en el código de cualquier otro lenguaje que no trabaje en la blockchain, lo podemos hacer sin problema alguno. Es cuestión de modificar y realizar un commit a nuestro repositorio si es que estamos trabajando con Git. Pero cuando se trata de trabajar con una red inmutable, esto se dificulta.

Por ende, documentar bien nuestros contratos es de vital importancia para los demás desarrolladores, ya que les brinda claridad a la hora de trabajar en una red que no permite margen de error. Veamos como podemos lograr esto en unos simples pasos:

Los comentarios son información valiosa

Si has visto o desarrollado cualquier Smart Contract, sabrás que estos mismos se ven mas o menos de la siguiente manera:

// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.4.16 <0.9.0;

contract Owner {
    address owner;

    function setOwner() public {
      owner = msg.sender;
  }
}

Ahora, si analizamos este código lo podemos entender fácilmente si tenemos conocimientos básicos de Solidity, pero cuando se trata de documentar nuestro código, este ejemplo está desastroso.

Solidity utiliza un estándar llamado NatSpec (Ethereum Natural Language Specification Format). Hagamos uso de este estándar y reescribamos el código anterior.

// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.4.16 <0.9.0;

/// @tittle <Título del contrato)
/// @author <Autor del contrato)
/// @notice <Para qué sirve este contrato)

contract Owner {
    address owner;

    /// @dev (Explicar que hace la función)
    function setOwner() public {
      owner = msg.sender;
  }
}

contract OwnerTransfer is Owner {
    /// @inheritdoc (Indica que el contrato hereda la documentación anterior)
    /// @param (Función del parámetro)
    /// @return msg.sender (Para qué sirve el retorno de la función)
    function setNewOwner(address _addr) public returns(address) {
      owner = _addr;
      return owner;
  }
}

Cada comentario tiene su propio contexto, acá te dejo una tabla para saber en que contexto y cuando utilizarlos:

Sigue aprendiendo sobre Solidity.

Si querés profundizar cada vez más sobre Solidity y poder desarrollar código limpio siguiendo las mejores prácticas, en mi perfil tenés más blogs acerca de cómo hacerlo.

Y recuerda: la blockchain es un ecosistema que requiere de conocimiento para utilizarla y no cometer errores graves, ayudémonos compartiendo información entre todos, por más mínima que sea. Todo comienza desde abajo.

• 📢 Redes sociales: Twitter, LinkdIn, Instagram.