Solidità - Guida allo stile

Style Guide aiuta a mantenere il layout del codice coerente e rendere il codice più leggibile. Di seguito sono riportate le migliori pratiche seguite durante la scrittura di contratti con Solidity.

Layout del codice

• Indentation- Usa 4 spazi invece di tab per mantenere il livello di rientro. Evita di mischiare gli spazi con le linguette.

• Two Blank Lines Rule - Utilizzare 2 righe vuote tra due definizioni di contratto.

pragma solidity ^0.5.0;

contract LedgerBalance {
   //...
}
contract Updater {
   //...
}

• One Blank Line Rule- Utilizzare 1 riga vuota tra due funzioni. In caso di sola dichiarazione non è necessario avere righe vuote.

pragma solidity ^0.5.0;

contract A {
   function balance() public pure;
   function account() public pure;
}
contract B is A {
   function balance() public pure {
      // ...
   }
   function account() public pure {
      // ...
   }
}

• Maximum Line Length - Una singola riga non deve attraversare 79 caratteri in modo che i lettori possano facilmente analizzare il codice.

• Wrapping rules- Il primo argomento deve essere in una nuova riga senza aprire parentesi. Usa un singolo rientro per argomento. Elemento terminale); dovrebbe essere l'ultimo.

function_with_a_long_name(
   longArgument1,
   longArgument2,
   longArgument3
);
variable = function_with_a_long_name(
   longArgument1,
   longArgument2,
   longArgument3
);
event multipleArguments(
   address sender,
   address recipient,
   uint256 publicKey,
   uint256 amount,
   bytes32[] options
);
MultipleArguments(
   sender,
   recipient,
   publicKey,
   amount,
   options
);

• Source Code Encoding - La codifica UTF-8 o ASCII deve essere utilizzata preferibilmente.

• Imports - Le istruzioni di importazione devono essere posizionate all'inizio del file subito dopo la dichiarazione pragma.

• Order of Functions - Le funzioni dovrebbero essere raggruppate secondo la loro visibilità.

pragma solidity ^0.5.0;

contract A {
   constructor() public {
      // ...
   }
   function() external {
      // ...
   }

   // External functions
   // ...

   // External view functions
   // ...

   // External pure functions 
   // ...

   // Public functions
   // ...

   // Internal functions
   // ...

   // Private functions
   // ...
}

• Avoid extra whitespaces - Evitare spazi bianchi immediatamente all'interno di parentesi, parentesi o parentesi graffe.

• Control structures- Le parentesi graffe dovrebbero aprirsi sulla stessa riga della dichiarazione. Chiudere sulla propria linea mantenendo la stessa rientranza. Usa uno spazio con parentesi graffa di apertura.

pragma solidity ^0.5.0;

contract Coin {
   struct Bank {
      address owner;
      uint balance;
   }
}
if (x < 3) {
   x += 1;
} else if (x > 7) {
   x -= 1;
} else {
   x = 5;
}
if (x < 3)
   x += 1;
else
   x -= 1;

• Function Declaration- Usa la regola sopra per le parentesi graffe. Aggiungi sempre un'etichetta di visibilità. L'etichetta di visibilità dovrebbe essere prima di qualsiasi modificatore personalizzato.

function kill() public onlyowner {
   selfdestruct(owner);
}

• Mappings - Evita gli spazi bianchi durante la dichiarazione delle variabili di mappatura.

mapping(uint => uint) map;
mapping(address => bool) registeredAddresses;
mapping(uint => mapping(bool => Data[])) public data;
mapping(uint => mapping(uint => s)) data;

• Variable declaration - Evita gli spazi bianchi durante la dichiarazione delle variabili di matrice.

uint[] x;  // not unit [] x;

• String declaration - Usa virgolette doppie per dichiarare una stringa invece di virgolette singole.

str = "foo";
str = "Hamlet says, 'To be or not to be...'";

Ordine di layout

Gli elementi dovrebbero essere disposti nel seguente ordine.

• Dichiarazioni di Pragma

• Importa dichiarazioni

• Interfaces

• Libraries

• Contracts

All'interno di interfacce, biblioteche o contratti l'ordine dovrebbe essere il seguente:

• Dichiarazioni di tipo

• Variabili di stato

• Events

• Functions

Convenzioni di denominazione

• Il contratto e la libreria devono essere denominati utilizzando lo stile CapWords. Ad esempio, SmartContract, Owner ecc.

• Il nome del contratto e della libreria devono corrispondere ai rispettivi nomi di file.

• In caso di più contratti / librerie in un file, utilizzare il nome del contratto / libreria principale.

Owned.sol

pragma solidity ^0.5.0;

// Owned.sol
contract Owned {
   address public owner;
   constructor() public {
      owner = msg.sender;
   }
   modifier onlyOwner {
      //....
   }
   function transferOwnership(address newOwner) public onlyOwner {
      //...
   }
}

Congress.sol

pragma solidity ^0.5.0;

// Congress.sol
import "./Owned.sol";

contract Congress is Owned, TokenRecipient {
   //...
}

• Nomi strutturali

  - Usa lo stile CapWords come SmartCoin.

• Nomi degli eventi

  - Usa lo stile CapWords come Deposito, AfterTransfer.

• Nomi delle funzioni

  - Usa lo stile mixedCase come initiateSupply.

• Variabili locali e di stato

  - Usa lo stile mixedCase come creatorAddress, supply.

• Costanti

  - Utilizza tutte le lettere maiuscole con trattino basso per separare parole come MAX_BLOCKS.

• Nomi dei modificatori

  - Usa lo stile mixCase come onlyAfter.

• Enum Names

  - Usa lo stile CapWords come TokenGroup.