نظرات در جاوا: همه چیز به این سادگی نیست

معرفی

نظرات - به نظر می رسد که می تواند ساده تر باشد و چرا یک مقاله کامل بنویسید. اما به این سادگی نیست. همانطور که رئیس من گفت، هر کسی می تواند کد بنویسد، اما نوشتن یک نظر خوب دشوار است. اکثر دوره های زبان با Hello World شروع می شوند. حتی در Oracle Tutorials، در بخش "شروع به کار"، ما با "Hello World!" کاربرد . و از همان اولین خطوط کد ما آنها را می بینیم - نظرات جاوا. اهمیت آنها همچنین با این واقعیت مورد تأکید قرار می گیرد که در سند مهمی مانند کنوانسیون کد جاوا، نظرات بخش جداگانه ای داده شده است: نظرات . با توجه به مستندات، نظرات در جاوا به دو نوع تقسیم می شوند:

• نظر پیاده سازی (یا نظر کد)؛
• مستندسازی نظر

نظرات کد برای توصیف خطوط/بلوک‌های مجزا و نظرات مستندات برای توصیف مشخصات کد (رابط آن) مستقل از اجرای آن استفاده می‌شود. نظرات جاوا توسط کامپایلر نادیده گرفته می شود زیرا آنها برای توسعه دهنده معنا دارند نه کاربر. بنابراین می توانید حجم کلاس های کامپایل شده را کاهش دهید.

نظرات کد جاوا

از نام مشخص است که این نظر به کد مربوط می شود و باید ویژگی های آن را منعکس کند. نظرات کد عبارتند از:

• حروف کوچک (یعنی در یک خط توضیح داده شده است)

  // Строчный комментарий
  System.out.println("Hello, World!");




• بلوک (یعنی آنها به عنوان یک بلوک کامل توصیف می شوند، زیرا در یک خط قرار نمی گیرند)

  /*
   * Блочный комментарий
   */
  System.out.println("Hello");

یکی از ویژگی‌های جالب کامنت بلاک این است که اگر آن را با " /*- " شروع کنیم (یعنی علامت منفی بعد از ستاره اضافه کنیم)، متن این نظر بلوک قالب بندی نمی شود. جالب است، اما با کمک نظرات خاص می توانید برخی نکات IDE را ارائه دهید. به عنوان مثال، با استفاده از نظرات درون خطی " //@formatter:on " و " //@formatter:off " در Eclipse IDE می توانید قالب بندی بخش هایی از کد را غیرفعال کنید. باید از نظرات به اندازه کافی و فقط در صورت لزوم استفاده کنید. به عنوان مثال، می‌توانید مقاله‌ای در این زمینه بخوانید: «در مورد کد نظر ننویسید!» . یک کتاب عالی به نام Clean Code: Creating, Analysing, and Refactoring نوشته رابرت مارتین وجود دارد . این یک فصل جداگانه "نظرات" دارد. به عنوان خلاصه ای از این فصل، یک نقل قول به همان اندازه عالی: «کد بد را نظر ندهید - آن را بازنویسی کنید» از برایان دبلیو کرنیگان و پی. جی. پلوور. این فصل را می‌توانید در Google Books پیدا کنید . معنای کلی را می توان در یک نقل از او بیان کرد:

هر بار که نظر می دهید، خم شوید و احساس کنید که یک شکست خورده اید."

واضح است که هیچ حقیقت مطلقی وجود ندارد و گاهی اظهار نظر لازم است. اما همیشه گزینه هایی وجود دارد و باید با نظرات غیر ضروری مبارزه کرد. این فصل همچنین به نظرات غیرمعمول، TODO اشاره می کند:

// TODO: Добавить World
System.out.println("Hello, ");

نکته آنها این است که می توان آنها را به روشی خاص در IDE مدیریت کرد. به عنوان مثال، در IDEA آنها در یک برگه جداگانه جمع آوری می شوند، جایی که می توانید آنها را مشاهده کنید: و یک معمای کوچک با یک نظر: خط "http://google.com" یک خط معتبر در داخل روش است، زیرا http در اینجا در واقع یک برچسب و سپس یک نظر است. اغلب بسیاری از نظرات می توانند از نظرات کد به نظرات اسناد تبدیل شوند که بعداً در مورد آنها صحبت خواهیم کرد.

نظرات برای مستندات

نظرات اسناد، API عمومی را توصیف می کنند. API رابط برنامه نویسی برنامه است، یعنی آن دسته از کلاس ها و روش هایی که برای انجام هر عملی در دسترس توسعه دهندگان دیگر است. به طور خلاصه، این نظرات باید توضیح دهند که چرا این یا آن کلاس و بسته ایجاد شده است و این یا آن متد چه کاری انجام می دهد. در صورت لزوم می توانید فیلدهای کلاس را نیز توضیح دهید. این دقیقاً همان چیزی است که ما در راهنمای ابزارهای IDE خود می بینیم که به عنوان JavaDoc ارائه شده است. مثلا: اگر به این روش برویم، می توانیم ببینیم که این متن از کجا آمده است: مجدداً به کنوانسیون کد جاوا: کنوانسیون کد در مورد نحوه فرمت صحیح JavaDoc مراجعه کنید . آنها تا حدودی شبیه به بلوک نظرات هستند، اما به جای یک ستاره (نه Asterix)) از دو استفاده می شود. یک مثال JavaDoc در بالا آورده شد. هیچ فایده ای برای توصیف همه احتمالات وجود ندارد، زیرا قبلاً در اسناد رسمی Oracle در مورد آن نوشته شده است. بنابراین، ما در اسناد رسمی JavaDoc ، بخش "توضیحات برچسب" به هر چیزی که نیاز دارید نگاه می کنیم. Oracle حتی یک آموزش جداگانه در مورد این موضوع دارد: نحوه نوشتن نظرات Doc برای ابزار Javadoc . نکات ابزار در IDE خوب هستند، اما در واقع به دلایلی سند هستند. بر اساس این نظرات JavaDoc، مستندات ایجاد می شود. یک ابزار جاوادوک مخصوص برای این کار وجود دارد . همانطور که می بینیم، آن آموزش در مورد این صحبت می کند. توضیح نحوه استفاده از آن در وب سایت رسمی Oracle برای JavaDoc وجود دارد . برای اینکه خودتان ببینید این به چه شکل است، می توانید یک زیر شاخه با نام بسته در فهرست ایجاد کنید، به عنوان مثال: test . یک کلاس ساده با نظرات در آن ایجاد کنید. مثلا:

package test;

/**
 * This is a JavaDoc class comment
 */
public class JavaDocTest {

  /**
   * This is a JavaDoc public field comment
   */
  public static final String HELLO_MESSAGE = "Hello, World!";

  public static void main(String... args) {
    JavaDocTest.greetings();
  }

  /**
   * This is a JavaDoc public method comment
   */
  public static void greetings() {
    System.out.println(HELLO_MESSAGE);
  }
}

پس از این، می‌توانیم دستور زیر را از دایرکتوری حاوی دایرکتوری بسته ما اجرا کنیم: javadoc -d ./test test پس از این، فرآیند تولید اسناد را مشاهده خواهیم کرد. و سپس می توانیم index.html را باز کنیم تا سند تولید شده را ببینیم. اغلب می بینید که اسناد API پست می شود. به عنوان مثال، Spring Framework API .

نتیجه

همانطور که می بینیم، چنین چیزی به ظاهر ساده مانند نظرات در واقعیت بسیار پیچیده تر است. بنابراین، اگر مدتی را صرف نظرات کنید و آنها را دنبال کنید، کد شما بهتر می شود و به عنوان یک برنامه نویس ارزش بیشتری خواهید داشت. #ویاچسلاو