التعليقات في Java: ليس كل شيء بهذه البساطة

مقدمة

التعليقات - يبدو أنه يمكن أن يكون الأمر أسهل، ولماذا أكتب مقالا كاملا. لكن الأمر ليس بهذه البساطة. كما قال مديري، يمكن لأي شخص كتابة التعليمات البرمجية، ولكن كتابة تعليق جيد أمر صعب. تبدأ معظم دورات اللغة ببرنامج Hello World التقليدي. حتى في برامج Oracle التعليمية، في قسم "البدء"، نبدأ بـ "Hello World!" طلب . ومن الأسطر الأولى من التعليمات البرمجية نراها - تعليقات جافا. يتم التأكيد على أهميتها أيضًا من خلال حقيقة أنه في وثيقة مهمة مثل اتفاقية كود Java، يتم إعطاء التعليقات قسمًا منفصلاً: التعليقات . وفقًا للوثائق، تنقسم التعليقات في Java إلى نوعين:

• تعليق التنفيذ (أو تعليق الكود)؛
• تعليق توثيقي.

تُستخدم تعليقات الكود لوصف الأسطر/الكتل الفردية، وتُستخدم تعليقات التوثيق لوصف مواصفات الكود (واجهته) بشكل مستقل عن تنفيذه. يتم تجاهل تعليقات Java بواسطة المترجم بسبب أنها منطقية للمطور، وليس للمستخدم. لذلك، يمكنك تقليل حجم الفئات المترجمة.

تعليقات كود جافا

يتضح من الاسم أن هذا التعليق يتعلق بالكود ويجب أن يعكس ميزاته. تعليقات الكود هي:

• أحرف صغيرة (أي موصوفة في سطر واحد)

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




• الكتلة (أي توصف بأنها كتلة كاملة، لأنها لا تتناسب مع سطر واحد)

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

من الميزات المثيرة للاهتمام في التعليق الجماعي أننا إذا بدأناه بـ " /*- " (أي أضفنا علامة الطرح بعد العلامة النجمية)، فلن يتم تنسيق نص التعليق الكتلي هذا. مثير للاهتمام، ولكن بمساعدة بعض التعليقات يمكنك تقديم بعض تلميحات IDE. على سبيل المثال، باستخدام التعليقات المضمنة " //@formatter:on " و " //@formatter:off " في Eclipse IDE، يمكنك تعطيل تنسيق أقسام التعليمات البرمجية. تحتاج إلى استخدام التعليقات بشكل مقتصد وفقط عند الضرورة. على سبيل المثال، يمكنك قراءة مقال حول هذا الموضوع: "لا تكتب تعليقات على الكود!" . يوجد كتاب رائع بعنوان " الشفرة النظيفة: الإنشاء والتحليل وإعادة البناء" بقلم روبرت مارتن. يحتوي على فصل منفصل "التعليقات". كاقتباس لهذا الفصل، يوجد اقتباس ممتاز أيضًا: "لا تعلق على تعليمات برمجية سيئة - أعد كتابتها" من Brian W. Kernighan وP. J. Plower. يمكن العثور على هذا الفصل في كتب Google . ويمكن التعبير عن المعنى العام في اقتباس واحد منه:

في كل مرة تعلق فيها، تجفل وتشعر بالفشل".

من الواضح أنه لا توجد حقيقة مطلقة، وفي بعض الأحيان تكون التعليقات ضرورية. ولكن هناك دائما خيارات، ويجب محاربة التعليقات غير الضرورية. يذكر هذا الفصل أيضًا التعليقات غير العادية، TODO:

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

المغزى منها هو أنه يمكن التعامل معها بطريقة خاصة في IDE. على سبيل المثال، في IDEA يتم جمعها في علامة تبويب منفصلة، ​​حيث يمكنك عرضها: ولغز صغير مع تعليق: السطر “http://google.com” هو خط صالح داخل الطريقة، لأنه http هنا هو في الواقع علامة، ثم تعليق. في كثير من الأحيان يمكن أن تنتقل العديد من التعليقات من تعليقات التعليمات البرمجية إلى تعليقات التوثيق، والتي سنتحدث عنها لاحقًا.

تعليقات للتوثيق

تصف تعليقات التوثيق واجهة برمجة التطبيقات العامة. API هي واجهة برمجة التطبيقات، أي تلك الفئات والأساليب المتاحة للمطورين الآخرين لتنفيذ أي إجراءات. باختصار، يجب أن تشرح هذه التعليقات سبب إنشاء هذه الفئة والحزمة أو تلك وما تفعله هذه الطريقة أو تلك. يمكنك أيضًا وصف حقول الفصل إذا لزم الأمر. هذا هو بالضبط ما نراه في تلميحات أدوات بيئة التطوير المتكاملة الخاصة بنا، والتي يتم تقديمها على شكل JavaDoc. على سبيل المثال: وإذا انتقلنا إلى هذه الطريقة، يمكننا أن نرى من أين يأتي هذا النص: مرة أخرى، راجع اتفاقية كود Java: اتفاقية الكود حول كيفية تنسيق JavaDoc بشكل صحيح . إنها تشبه إلى حد ما حظر التعليقات، ولكن بدلاً من علامة النجمة الواحدة (وليس أستريكس)) يتم استخدام اثنتين. تم تقديم مثال JavaDoc أعلاه. ليس هناك أي معنى لوصف كل الاحتمالات، لأنه مكتوب بالفعل في وثائق أوراكل الرسمية. ولذلك، فإننا ننظر إلى كل ما نحتاجه في وثائق JavaDoc الرسمية ، قسم "أوصاف العلامات". لدى Oracle أيضًا برنامج تعليمي منفصل حول هذا الموضوع: كيفية كتابة تعليقات المستند لأداة Javadoc . تعد تلميحات الأدوات الموجودة في IDE رائعة، ولكنها في الواقع مستندات لسبب ما. بناءً على تعليقات JavaDoc هذه، يتم إنشاء الوثائق. هناك أداة 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 .

خاتمة

كما نرى، فإن الشيء الذي يبدو بسيطًا كالتعليقات، يتبين أنه أكثر تعقيدًا في الواقع. لذلك، إذا قضيت بعض الوقت في التعليقات ومتابعتها، فإن شفرتك ستكون أفضل وستكون أكثر قيمة كمبرمج. # فياتشيسلاف