Solidność - przewodnik po stylu

Przewodnik po stylach pomaga zachować spójny układ kodu i uczynić go bardziej czytelnym. Oto najlepsze praktyki, które należy stosować podczas pisania umów z Solidity.

Układ kodu

• Indentation- Użyj 4 spacji zamiast tabulatora, aby zachować poziom wcięcia. Unikaj mieszania spacji z tabulatorami.

• Two Blank Lines Rule - Użyj 2 pustych wierszy między dwiema definicjami kontraktu.

pragma solidity ^0.5.0;

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

• One Blank Line Rule- Użyj 1 pustej linii między dwiema funkcjami. W przypadku samej deklaracji nie trzeba mieć pustych wierszy.

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 - Pojedyncza linia nie powinna przekraczać 79 znaków, aby czytelnicy mogli łatwo przeanalizować kod.

• Wrapping rules- Pierwszy argument należy umieścić w nowej linii bez otwierającego nawiasu. Użyj jednego wcięcia na argument. Element kończący); powinien być ostatni.

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 - Zaleca się stosowanie kodowania UTF-8 lub ASCII.

• Imports - Deklaracje importu należy umieścić na górze pliku zaraz po deklaracji pragmy.

• Order of Functions - Funkcje należy pogrupować według ich widoczności.

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 - Unikaj białych znaków bezpośrednio w nawiasach, nawiasach lub nawiasach klamrowych.

• Control structures- Nawiasy powinny otwierać się w tym samym wierszu co deklaracja. Zamykają we własnej linii, zachowując to samo wcięcie. Użyj spacji z nawiasem otwierającym.

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- Zastosuj powyższą zasadę dla szelek. Zawsze dodawaj etykietę widoczności. Etykieta widoczności powinna znajdować się na pierwszym miejscu przed jakimkolwiek modyfikatorem niestandardowym.

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

• Mappings - Unikaj białych znaków podczas deklarowania zmiennych mapujących.

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

• Variable declaration - Unikaj białych znaków podczas deklarowania zmiennych tablicowych.

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

• String declaration - Użyj podwójnych cudzysłowów, aby zadeklarować ciąg znaków zamiast pojedynczego cudzysłowu.

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

Kolejność układu

Elementy należy układać w następującej kolejności.

• Oświadczenia pragmy

• Import wyciągów

• Interfaces

• Libraries

• Contracts

W ramach interfejsów, bibliotek lub umów kolejność powinna wynosić -

• Deklaracje typów

• Zmienne stanu

• Events

• Functions

Konwencje nazewnictwa

• Kontrakt i Biblioteka powinny być nazwane przy użyciu stylu CapWords. Na przykład SmartContract, właściciel itp.

• Nazwy kontraktu i biblioteki powinny być zgodne z nazwami plików.

• W przypadku wielu umów / bibliotek w pliku, użyj nazwy podstawowego kontraktu / biblioteki.

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 {
   //...
}

• Nazwy struktur

  - Używaj stylu CapWords jak SmartCoin.

• Nazwy wydarzeń

  - Używaj stylu CapWords, takiego jak depozyt, po przeniesieniu.

• Nazwy funkcji

  - Użyj stylu mixedCase, np. InitialateSupply.

• Zmienne lokalne i stanowe

  - Użyj stylu mixedCase, np. CreatorAddress, supply.

• Stałe

  - Użyj wszystkich wielkich liter z podkreśleniem, aby oddzielić słowa, takie jak MAX_BLOCKS.

• Nazwy modyfikatorów

  - Użyj stylu mixCase jak onlyAfter.

• Nazwy wyliczeń

  - Używaj stylu CapWords jak TokenGroup.