سلام به همگی دوستان و همراهان آقای مبتدی (مستر جونیور)!
اگر شما هم میخواهید کامنت هاتون در زبان برنامه نویسی Solidity و قرارداد های هوشمندی که توسعه میدید یک فرمت و ساختار منظم و قابل فهم تری داشته باشه، این مقاله رو از دست ندید!
بخش اول: NatSpec چی هست و چه کاربردی داره؟
در سالیدتی (Solidity) شما میتونید برای توسعه Smart Contract ها از یک فرمت خاص برای نوشتن کامنت استفاده کنید که NatSpec نامیده میشه که Doxygen هم الهام گرفته شده (نیاز نیست الان بدونید Doxygen چی هست 🙂 )
NatSpec مخفف Ethereum Natural Language Specification Format هست!
این فرمت نوشتن کامنت در زبان Solidity هم برای کامپایلر (Compiler) قابل مفهوم هست و هم برای انسان به راحتی قابل درک،
حالا بریم داخل کد و به صورت عملی اون رو یاد بگیریم،
برای نوشتن کامنت در Solidity شما قبلا به چه صورت اینکارو انجام میدادید؟ خیلی راحت از // برای کامنت های تک خطی (single-line) و از /* */ برای کامنت های چند خطی (multi-line) که کاملا مشابه زبان JavaScript هست، درسته؟ (به این سبک کامنت های single-line یا تک خطی همچنین C++-style هم گفته میشه چون از زبان ++C الهام گرفته شده و به کامنت های multi-line یا چند خطی C-style هم گفته میشه به این دلیل که از زبان C الهام گرفته شده، این رو گفتم که اگر جایی دیدید یا شنیدید متوجه بشید منظور چیست هست!)
اما در فرمت NatSpec شما باید برای کامنت های تک خطی از /// و برای کامنت های چند خطی از /* **/ استفاده کنید، چرا؟ چون برای کامپایلر از پیش تعریف شده که هر موقع چنین سینتکس و ساختاری رو مشاهده کرد بدونه NatSpec هست و به علاوه اینکه داخل code editorتون هم کامنت ها خیلی بهتر تر نمایش داده میشوند،
در شیوه کامنت گذاری NatSpec شما یکسری تگ های از پیش تعریف شده و آماده دارید که مشخص میکنند این خط از کامنت باید درمورد چه موضوعی توضیح بدید یا چه چیزی رو شفاف تر بیان کنید،
در واقع این تگ ها یک جورایی اومدن و به طبقه بندی و منظم کردن کامنت هاتون در سالیدتی کمک کردن!!!
جلوتر که چندتا مثال بزنم کامل درک میکنید، اما قبلش بهتره که لیست این تگ هارو با هم ببینیم؛
نکته مهم: دوستان دقت داشته باشید همونطور که در ادامه متوجه خواهید شد استفاده از تمامی این تگ ها کاملا اختیاری و دل‌بخواه هست و شما کافیه بسته به context یا اون کامنتی که میخواهید بزارید از این تگ ها استفاده کنید، به هیچ عنوان نیازی نیست برای هر بلاک کد بیاید از تمامی این تگ ها استفاده کنید.
این از این! خب در ستون اول از سمت چپ لیست تگ های از پیش تعریف شده رو مشاهده میکنید که با @ شروع میشوند، و اگر یک مقداری دقت کنید میبینید که از روی عنوان هاشون کاملا میشه متوجه شد در مورد چه موضوعی هستند!
در ستون دوم توضیح داده که برای چی باید از این تگ ها استفاده کنید، نگران نباشید من جلوتر هر کدوم رو شرح میدم 🙂
و در ستون سمت چپ مشخص کرده که باید کجا از اون تگ استفاده کنید!
یک نگاهی به Contract زیر بندازید تا بیشتر با این شیوه آشنا بشید. (در ادامه مثال ها حول محور همین کانترکت میچرخه)
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.8.2 < 0.9.0;
/** @title A simulator for trees
* @author Larry A. Gardner
* @notice You can use this contract for only the most basic simulation
* @dev All function calls are currently implemented without side effects
* @custom:experimental This is an experimental contract.
*/
contract Tree {
/// @notice Calculate tree age in years, rounded up, for live trees
/// @dev The Alexandr N. Tetearing algorithm could increase precision
/// @param rings The number of rings from dendrochronological sample
/// @return Age in years, rounded up for partial years
function age(uint256 rings) external virtual pure returns (uint256) {
return rings + 1;
}
/// @notice Returns the amount of leaves the tree has.
/// @dev Returns only a fixed number.
function leaves() external virtual pure returns(uint256) {
return 2;
}
}
contract Plant {
function leaves() external virtual pure returns(uint256) {
return 3;
}
}
contract KumquatTree is Tree, Plant {
function age(uint256 rings) external override pure returns (uint256) {
return rings + 2;
}
/// Return the amount of leaves that this specific kind of tree has
/// @inheritdoc Tree
function leaves() external override(Tree, Plant) pure returns(uint256) {
return 3;
}
}
همونطور که احتمالا متوجه شدید واقعا ساختار سخت و پیچیده‌ای نیست! با یک نگاه کردن احتمالا یادش گرفتید، خیلی ساده هست، بریم یک مقدار مثال بالا رو بررسی کنیم،
کامنتی که برای کانترکت Tree گذاشته شده به صورت multi-line یا چند خطی هست، پس همونطور که بالاتر توضیح دادم با **/ شروع و با */ تموم میشه، حالا در این بین ما اومدیم برای توضیح دادن قسمت های مختلف کامنت از تگ های از پیش تعریف شده (لیست بالا) استفاده کردیم،
دقت داشته باشید که ما برای هر تگ در multi-line comments ما به صورت جدا و مجزا از علامت * (asterisk نامید میشه) استفاده میکنیم که باعث میشه کامنت هامون خیلی منظم تر و بهتر نمایش داده بشن!
نکته: همچنین اینجا میشد تمام این تگ هارو به صورت زیر هرکدوم رو در یک کامنت تک خطی هم نوشت اما وقتی ما داریم از تعداد زیادی تگ استفاده میکنیم خصوصا هنگام تعریف Contract ها بهتره که از multi-line کامنت ها استفاده کنیم.
....
/// @title A simulator for trees
/// @author Larry A. Gardner
/// @notice You can use this contract for only the most basic simulation
/// @dev All function calls are currently implemented without side effects
/// @custom:experimental This is an experimental contract.
contract Tree {
.....در عکس زیر مشاهده میکنید که مثال بالا در VSCode به چه شکل نمایش داده میشه:
بخش دوم: شرح تگ های NatSpec
خب حالا بریم هر کدوم از تگ های آماده NatSpec که در لیستی زیر مشاهده میکنید رو یاد بگیریم:
۱. تگ title@: داخل این تگ شما خیلی ساده یک عنوان جهت توضیح مختصر اون Contract, library یا interface مشخص میکنید، از این تگ در contract، library و interface ها میتونید استفاده کنید (در جاهای دیگر هم میشه اما واقعا نیازی نیست)
۲. تگ author@: بعد از نوشتن این تگ شما اسم توسعه دهنده و برنامه نویس اون کانترکت رو مشخص میکنید، از این تگ هم مشابه title میتونید در contract، library و interface ها استفاده کنید.
۳. تگ notice@: این یکی از تگ های نسبتا پرکاربرد هست که شما باید در این تگ به end-user (کاربر نهایی، کلاینت شما – مشتری) خیلی ساده توضیح بدید که به طور مثال این فانکشن چیکار میکنه، فرض کنید کلاینت شما بدون داشتن هیچ دانشی از برنامه نویسی میخواد یک نگاه خیلی سریع و ساده به کد بندازه، شما باید سعی کنید به نحوی عملکرد function رو توضیح بدید که اون شخص هم تا حدی متوجه بشه!
همونطور که در لیست بالا ذکر شده از این تگ تقریبا برای تمامی بخش های کد اعم از contract, library, interface, function, public state variable, event ها میتونید استفاده کنید.
۴. تگ dev@: این تگ مشابه تگ notice هست با این تفاوت که در notice@ شما به کاربر نهایی (end user) توضیح میدید اما در این تگ به همکارانتون 🙂 خیلی ساده اگر مواردی که هست دولوپر بعدی یا حتی خودتون قراره راجبه این بلاک از کد بدونید رو میتونید اینجا بنوسید،
دقیقا مثل notice@ از این تگ هم میتونید برای تمامی بخش ها اعم از contract, library, interface, function, public state variable, event ها استفاده کنید.
۵. تگ param@: در این تگ شما میتونید برای یک پارامتر (parameter) توضیحی رو بنویسید! به طور مثال اگر داخل فانکشنی پارامتری تعریف کردید که احساس میکنید ممکنه گنگ به نظر برسه میتونید از تگ param@ همراه با نام اون پارامتر توضیحاتی رو درباره اون بدید؛
دقت داشته باشید وقتی از این تگ استفاده میکنید، حتما باید بعدش نام اون پارامتر مد نظرتون رو بنویسید؛
مثال:
/// @param rings The number of rings from folan sample :/
function age(uint256 rings, string memory name) external pure returns (uint256) {
.....بعد از نوشتن تگ param@ پارامتر رو مشخص کرده که در اینجا rings هست و حالا بعدش اون رو سعی کرده ۰۰۰۰۰۰شرح بده؛
از این تگ باید در function ها و event ها استفاده کنید. (طبیعی هم هست مثلا یک contract پارامتری نداره که بخواهید از این تگ براش استفاده کنید)
۶. تگ return@: از این تگ برای شرح دادن متغیر یا مقادیری که قرار فانکشن return کنه استفاده میکنید،
همچنین از این تگ برای function ها و public state variable ها میتونید استفاده کنید،
نکته مهم: دوست دارم دوباره این نکته رو یادآوری کنم که استفاده از تمامی این تگ ها اختیاری هست، یعنی نیازی نیست شما بخواهید هر مقداری که یک تابع بر میگردونه از این تگ یا اصلا تمامی تگ های دیگه استفاده بکنید! صرفا زمانی که صلاح دونستید به طور مثال این مقدار نیاز به یک توضیح مختصر یا یک note کوچک داره.
مثال:
/// @return Age in years, rounded up for partial years
function age(uint256 rings) public pure returns (uint256) {
return rings + 1;
}۷. تگ inheritdoc@: معمولا شما زمانی از این تگ استفاده میکنید که بخواهید بگید تمامی تگ هایی که در base function (تابع اصلی) هست رو من برای این تابع زیر مجموعه هم میخوام داشته باشم، به زبان ساده تر ارث بری تگ ها هستش، از این تگ هم در functions ها و public state variable ها میتونیم استفاده کنیم.
مثال: (این مثال ها بخش های مختلف همون کانترکت Tree هست که بالاتر آوردم)
/// @inheritdoc Tree
function leaves() external override(Tree, Plant) pure returns(uint256) {
return 3;
}۸. تگ …:custom@: خب با استفاده از این تگ میتونید تگ custom یا سفارشی خودتون رو داشته باشید و تعریف کنید! یعنی چی؟ مثلا فرض کنید خواستید درمورد یک موضوع خاصی کامنت قرار بدید که ارتباطی به هیچ کدوم از تگ های بالا نداره، از یک طرف هم نمی‌خواهید از یک تگ اشتباه و غیر مرتبط استفاده کنید،
در اینجا براحتی تگ custom@ رو مینویسید و بعد از علامت (: دونقطه) میاید و عنوان اون تگ رو کاملا به دلخواه نام گذاری میکنید و بعد کامنت که میخواستید رو می نویسید، از این تگ در هرکجا که خواستید میتونید به راحتی استفاده کنید و محدودیت خاصی از این بابت وجود نداره،
جهت نام‌گذاری custom tag ها باید حتما دقت داشته باشید که تمامی حروف کوچک (lowercase) باشند و هر کلمه با خط تیر، دش یا hyphen (-) از همدیگر جدا بشه، مثال:
/// @custom:experimental This is an experimental contract.
contract Tree {
...در اینجا مشاهده میکنید که کلمه experimental درواقع همون عنوان تگ هست و توضیحات بعدش با فاصله قرار گرفتند.
نتیجه گیری نهایی:
پس از این به بعد هر زمانکه خواستید در Solidity کامنت بنویسید، خیلی بهتره از فرمت NatSpec برای نوشتن کامنت هاتتون استفاده کنید، بسیار ساده هست، کلا از ۷ تا تگ آماده بیشتر تشکیل نشده که میتونید بسته به شرایطی که توضیح دادم ازشون استفاده کنید،
امیدوارم که این مقاله آموزشی بهتون کمک کرده باشه! خوشحال میشم نظراتتون رو بدونم، قطعا این مقاله به مرور زمان به کمک شما عزیزان تکمیل تر و اشکالاتش رفع خواهد شد!
مرسی از اینکه تا آخر این مقاله همراه من بودید.
ایولا👌 درجه یک