نوشتن داکیومنت موثر برای کد ها در فلاتر

امروز که کد می نویسیم آسونه که به کد نگاهی بکنیم و بگیم آره!! این کدیه که کار میکنه ولی بعد ها افراد دیگری قراره روی کد ما کار کنن و توسعه بدن، یا حتی خود ما بعد از مدتی (شاید سال ها بعد) بیایم روی کدی که نوشتیم بر بگردیم و اوووچ!! این دیگه برای چی نوشتم اینجا و الی آخر
نوشتن یک کامنت مختصر و دقیق ممکنه فقط چند ثانیه طول بکشه ولی همین کامنت، میتونه ساعت ها در وقت یک برنامه نویس دیگه یا حتی خود ما صرفه جویی بکنه

انواع کامنت در دارت

ما سه نوع کامت گذاری در دارت داریم

• نوع تک خطی که با دوتا اسلش نمایش میدن ( Comment //)
• نوع چند خطی که با اسل ستاره شروع و با ستاره اسلش خاتمه پیدا میکنه (/* Comment */)
• نوع سوم که بهش داکیومنتیشن کامنت هست که برای نوشتن داکیومنت از اون استفاده میشه و به دو صورت هست که با سه اسلش ( Comment ///) و اسلش سه تا ستاره اسلش (/* Comment **/)

نوشتن داکیومنت برای کد

• قبل از هر چیزی باید بگم که باید کد ها کلا خوانا باشه در نوشتار ولی جایی هست که برای درک بهتر کامنت گذاری می کنیم

برای نوشتن کامنت مثل جمله عمل میکنیم توی زبان لاتین که با کپتال (حرف اول باید بزرگ نوشته بشه) شروع میشه و برای نوشتن یک توضیح کوتاه برای یک خط کد معمولا از کامنت تک خطی استفاده میکنیم مثلا

void greet(String name) {  
 // Assume we have a valid name.   
 print('Hi, $name!'); 
}

• یه نکه اینکه از کامنت چند خطی معمولا برای کامنت کردن بخشی از کد استفاده میشه نه برای توضیح

حالا اگر بخوایم برای کلاس یا یک فایل داکیومنت بنویسیم از سه اسلش استفاده میکنیم و توضیحات رو مینویسم مثلا

class RadioButtonWidget extends Widget {
  /// Sets the tooltip to [lines].
  ///
  /// The lines should be word wrapped using the current font.
  void tooltip(List<String> lines) {
    ...
  }
}

• نکته اول اینکه ما توی کامنت های داکیومنت میتونیم رفرنس بدیم که مثلا با محیط برنامه نویسی وی اس کد با نگه داشتن دکمه کنترل کیبرد و کلیک روی اون رفرنس به محل رفرنس برید که با براکت ([ ]) رفرنس مون رو میدیم مثلا توی این مثال [lines] که توی کامنت هست رفنرس میده پارامتر tooltip
• نکته دوم، زمانی که اسم کلاس مثلا خیلی واضحه دیگه نیازی به کامنت اضافه نیست، حالا چرا؟ چون ممکنه باعث سردرگمی بشه توی این مثال اسم کلاس مشخصه که چه ویجتی هست
• نکته سوم، حد امکان کامنت داکیومنت خوانا و کم باشه بهتره
• نکته چهارم و آخر اینکه اگر چند جمله ای هست داک کامنتتون اون رو مثل مثال بالا جدا کنید یعنی جمله اول اگر تمام شد یه بریک لاین خالی هم با کامنت بذارید

استخراج داکیومنت هایی که نوشتیم بصورت یکجا

اگر با اصول ساخت نرم افزار آشنا باشید یه اصلی هست که میگه باید داکیومنت داشته باشی که حالا بصورت فیلم میتونی کد هاتو توضیح بدی یا بنویسی و ...

خب ما نیاز داریم که داکیومنت کدهامون بصورت یکجا به دست برنامه نویس بعدی یا سایرین باشه که بتونن از داکیومنت استفاده کنند که برای استخراج اینها دارت خودش یه کامندی داره با اجرای اون دستور کامنت ها استخراج میشن که اون دستور این هست

dart doc .

این دستور میگه که برای کد های من داکیومنت هاش رو توی پوشه روت جنریت کن و میاد داکیومنت های کد مارو بصورت یکجا در دسترس قرار میده

حالا اگر بخوایم بصورت لوکال در دسترس باشه و روی وب ببینیم کافیه دستورات زیر رو اجرا کنیم

dart pub global activate dhttpd
dart pub global run dhttpd --path doc/api

حالا داکیومنت های ما با آدرس http://localhost:8080در دسترس است

امیدوارم مطالب به درتون خورده باشه

منابع من برای این نوشته:

Effective Dart: Documentation | Dart

dart doc | Dart

Comments | Dart

Adnan Kamali | عدنان کمالی