スタイルガイドとは、何をどういう順番で記述するかとか、どのように記述するかという記述方法についてのガイドラインです。スタイルガイドに沿ったコーディングは、可読性の向上、メンテナンスの容易化、チーム間の統一、エラーの予防など、プロジェクトの品質や効率性を向上させるために重要です。統一されたコーディングスタイルを実践することは、長期的なプロジェクトの成功に不可欠な要素となります。
スタイルガイドの重要性
コーディングにおいてスタイルガイドに沿ったコーディングを行うことは以下のような重要な意味を持っています。
- 可読性の向上: スタイルガイドに従ったコーディングは、コードの可読性を高めます。コードを読む他の開発者や将来の自分自身が、より迅速かつ正確にコードを理解できるようになります。一貫した命名規則や適切なインデント、コメントの使用などは、コードの意図や機能を明確に伝えるために重要です。
- メンテナンスの容易化: スタイルガイドに従ったコーディングは、コードのメンテナンスを容易にします。一貫性のあるスタイルや構造を持つコードは、変更や修正を行う際にミスやハードルを減らし、バグの発生リスクを低くします。他の開発者がコードを理解しやすく、迅速に変更できるため、チームの生産性も向上します。
- チーム間のコードの統一: スタイルガイドは、開発チームやプロジェクト全体でコードの一貫性を確保するための重要なツールです。チーム全員が同じスタイルガイドに従ってコーディングを行うことで、コードベースが統一され、予測可能性が高まります。これにより、コードの相互運用性や共有性が向上し、コードの管理や協力が容易になります。
- エラーの予防: スタイルガイドは、一貫したコーディングスタイルを守ることによってエラーを予防する助けとなります。一貫したスタイルにより、潜在的なエラーを早期に発見しやすくなります。
スタイルガイド
コントラクト要素の記述順
以下の順番で記述します。
- pragma 文
- import 文
- Interface
- Library
- Contract
Interfaceは、interfaceキーワードを使用して作成されます。インターフェースは関数のプロトタイプ（シグネチャ）のみを持ち、実装の詳細は含みません（つまり、中身は未実装だが、どういう関数やイベントを備えているかを表明しているものになります）。
また、Libraryは、再利用可能なコードの集合体で、関数やデータ構造のセットを提供します。libraryキーワードを使用して作成されます。
次の例では、LibraryとContractを同じファイルに記述している例です。SafeMathというライブラリーを定義しており、Fundingコントラクトで利用されています。冒頭にSafeMathをuint256に対して適用するという宣言があり、こうすると、Funding内のuint256型の変数では、SafeMathで定義されている関数が利用可能になります。27行目では、SafeMathのadd関数が使われています。
// SPDX-License-Identifier: MIT
pragma solidity 0.8.13;
import "@openzeppelin/contracts/token/ERC20/ERC20.sol";
library SafeMath {
...
function add(uint256 a, uint256 b) internal pure returns (uint256) {
uint256 c = a + b;
assert(c >= a);
return c;
}
...
}
contract Funding {
// 型宣言
using SafeMath for uint256;
...
// 状態変数
mapping(address => uint256) private s_addressToAmount;
...
// 関数
function fund() public payable {
s_funders.push(msg.sender);
s_addressToAmount[msg.sender].add(msg.value); // SafeMathのadd関数が使える
emit Funded(msg.sender, msg.value);
}
...
}
コントラクト内の要素の記述順
- 型宣言 … 基本型以外に定義されている個別の型、enum, struct, library等
- 状態変数 … コントラクト内で使われる変数
- イベント
- Modifier
- 関数
各コントラクト（もしくはインターフェース、ライブラリー）の中での記述の順番は上記のとおりとなります。
次の例もあわせてご参照ください。実例として理解を深めることができます。
// SPDX-License-Identifier: MIT
pragma solidity 0.8.13;
contract Funding {
// 型宣言
using SafeMath for uint256;
// 状態変数
address[] private s_funders;
mapping(address => uint256) private s_addressToAmount;
address public i_owner = 0x5B38Da6a701c568545dCfcB03FcB875f56beddC4;
// イベント
event Funded(address indexed funder, uint256 indexed fundedAmount);
// modifier
modifier onlyOwner() {
require(msg.sender == i_owner, "Only contract owner can call this function");
_;
}
// 関数
function fund() public payable {
s_funders.push(msg.sender);
s_addressToAmount[msg.sender].add(msg.value);
emit Funded(msg.sender, msg.value);
}
...
}関数の記述順
- constructor
- receive
- fallback
- public
- internal
- private
- view/pure
constructor（初期化処理）にはじまり、それぞれ上記の順で書くことが推奨されています。実際にfunctionによる定義を行う対象は、public以降のもので、最初の３つは特殊な位置づけの関数になります。
receive関数は、コントラクトに対して直接ETHが送られた場合に自動的に呼び出される関数、fallback関数は、コントラクト内に定義されていない関数が呼び出された場合に実行されるコードを記述するための関数になります。
natspec
Natspecは、Solidityに組み込まれたドキュメンテーションツールであり、コントラクトや関数の説明やドキュメンテーションを記述するための仕組みです。NatspecはNatural Language Specification（自然言語仕様）の略称です。
Natspecを使用すると、コントラクトや関数に関する情報を明確に記述することができます。具体的には、コントラクトの目的、関数の機能、引数の意味、返り値の形式などをドキュメントとして提供します。
NatspecはSolidityのコメントとして書かれ、特定の構造とタグを使用してドキュメントを整理します。主なタグには以下のものがあります。
@title：コントラクトのタイトルや名前を指定します。これにより、コントラクトの識別やドキュメントの整理が容易になります。@author：コントラクトの作成者や著作権情報を指定します。これにより、コントラクトの著作権情報を明示することができます。@notice：コントラクトや関数の使用方法、注意事項、重要な情報などを提供します。ユーザーに対して重要な情報を伝えるために使用されます。@dev：開発者向けの情報を提供するためのタグです。関数の内部ロジックや実装の詳細など、コントラクトの内部での使用方法に関する情報を記述します。@param：関数の引数に関する説明を提供するためのタグです。引数の名前、型、意味などを記述します。@return：関数の返り値に関する説明を提供するためのタグです。返り値の型や意味などを記述します。
/**
* @title A contract for crowdfunding
* @author simochan
* @notice This contract is to demo a sample funding contract
* @dev This implements price feeds as our library
*/
contract Funding {
// Type Declarations
using PriceConverter for uint256;
...
}
ご意見をお聞かせください！
この記事、または、web3チュートリアル全体について、是非、あなたのご意見をお聞かせください。
アンケートはこちらからご回答いただけます。
無料相談承ります
オンラインでの無料相談を承っています。ご希望の方は、お問い合わせフォームよりご連絡ください。
ITの専門家があなたのご質問にお答えいたします。
Comments