تعليقات جافا

التعليقات هي جزء من البرنامج الذي لم يتم تنفيذه. يتجاهل المترجم التعليقات ببساطة لأنها غير مخصصة لها. إنها مكتوبة بلغة "إنسانية" وتهدف إلى شرح البرنامج، أو جزء منه، أو سطر واحد أو طريقة واحدة للمطورين أو الأشخاص المشاركين في التطوير. في أغلب الأحيان، تتم كتابة التعليقات باللغة الإنجليزية، وهو نوع من التقليد. سنتحدث في هذه المقالة عن التعليقات في Java وكيفية استخدامها بشكل صحيح لتسهيل الحياة عليك وعلى زملائك في الفريق.

تعليقات جافا: لماذا هي مهمة

يقولون أن المبرمجين كسالى للغاية عندما يتعلق الأمر بالتعليق على الكود الخاص بهم. ومع ذلك، فهذه مهارة مهمة للغاية، لذا لا تقلل من أهميتها، حتى لو كنت قد بدأت للتو في تعلم Java. تعد التعليمات البرمجية التي تم التعليق عليها جيدًا أكثر قيمة من التعليمات البرمجية بدون تعليقات لأن صيانة مثل هذا البرنامج أسهل بكثير. نظرًا لأن المشاريع الكبيرة غالبًا ما تتم كتابتها بلغة Java، فإن التعليق المختص يؤدي أيضًا إلى تسريع عملية التطوير، حيث يسهل على المبرمج التعامل مع أكواد الآخرين. التعليقات مطلوبة من أجل:

• افهم الكود. لك أو لشخص آخر. إذا بدا لك أنك لست بحاجة إلى فك رموز الكود الخاص بك لأنك كتبته، فحاول فتح برنامج معقد نسبيًا كتبته قبل شهر أو حتى قبل ذلك، وافهم بسرعة ما الذي يدور في ذهنك وأين ولماذا. يمكن استخدام التعليقات لشرح منطق البرنامج أو كتلة البرنامج، بالإضافة إلى ترك توصيات لأولئك الذين سيعملون مع التعليمات البرمجية الخاصة بك لاحقًا. يمكن تسمية هذا النوع من التعليقات بالتعليقات التوضيحية.

• تحتوي على معلومات حول الغرض من الكائنات ومعلمات الإدخال والإخراج (إن وجدت) وبيانات حول المطور والأشياء المهمة الأخرى المتعلقة بجزء التعليمات البرمجية. توجد هذه التعليقات في رؤوس الوحدات والمكتبات والإجراءات والوظائف. يمكن أن يطلق عليها تعليقات التوثيق.

• السيطرة على الأخطاء وتحسين التعليمات البرمجية. يمكن دائمًا التعليق على التعليمات البرمجية المشكوك فيها أو التعليمات البرمجية التي تحتاج إلى تحسين وإعادة النظر فيها لاحقًا. إذا خطر لك أن مشكلة معينة يمكن حلها بطريقة مختلفة، ولكن الآن ليس لديك الوقت لذلك، اكتب هذه الفكرة في التعليق. خلاف ذلك، على الأرجح، تحت ضغط التعليمات البرمجية الجديدة، سوف تنسى ذلك.

أنواع التعليقات في جافا

على الرغم من أنه يمكنك كتابة أي شيء وكل شيء في التعليقات، إلا أن هناك أنواعًا معينة من التعليقات في Java وقواعد لاستخدامها. في تعليقات جافا يكون باردًا:

• تعليقات سطر واحد
• تعليقات متعددة الأسطر
• تعليقات التوثيق

تعليقات سطر واحد

تعليقات Java الأكثر شيوعًا هي التعليقات ذات السطر الواحد. للإشارة إلى مثل هذا التعليق، يكفي وضع شرطة مائلة مزدوجة قبل النص // . يتم وضع علامة على تعليقات السطر الواحد فقط في بداية التعليق. يستمر التعليق حتى نهاية السطر. بناء الجملة:

//here is a single line comment.

لنأخذ مثالاً على هذا النوع من تعليقات Java:

public class CommentsDemo1 {
   public static void main(String[] args) {
       System.out.println("This text is visible for Java compiler");
       //this text is single line comment
//This one is also single line comment
//they both (and me) are invisible for compiler
   }
}

الإخراج هو: عادةً ما يوجد تعليق من سطر واحد أعلى أو أسفل مكان التعليق في البرنامج، وأحيانًا على نفس السطر. من المهم أن يكون واضحًا بصريًا ما يشير إليه التعليق.

تعليقات متعددة الأسطر

في بعض الأحيان لا يوجد سطر واحد كافٍ لكتابة تعليق Java. على سبيل المثال، تحتاج إلى وصف كيفية عمل إحدى الطرق أو الصيغة المعقدة التي تقوم بتنفيذها. في هذه الحالة، يمكنك كتابة عدة تعليقات من سطر واحد، ولكن سيكون من الأكثر عقلانية كتابة ما يسمى بالتعليقات متعددة الأسطر. تم تمييزها على كلا الجانبين بالرموز /* */ . بناء جملة التعليقات متعددة الأسطر:

/*This comment
is
Multi line comment
we can describe here
what we need */

لنأخذ مثالاً على التعليقات متعددة الأسطر في الكود

public class RleTest {

   /*
   Run Length Encoding (RLE),  a data compression algorithm
   that replaces repeated characters (series)
   with one character and the number of its repetitions.

   this method is to decode a String using run-length encoding

    */
   private static String decodeRle(String encoded) {
       if (encoded.isBlank()) return "";
       StringBuilder result = new StringBuilder();
       int count = 0;
       char baseChar = encoded.charAt(0);
       for (int i = 1; i <= encoded.length(); i++) {
           char c = i == encoded.length() ? '$' : encoded.charAt(i);
           if (Character.isDigit(c)) {
               count = count * 10 + Character.digit(c, 10);
           } else {
               do {
                   result.append(baseChar);
                   count--;
               } while (count > 0);
               count = 0;
               baseChar = c;
           }
       }
       return result.toString();
   }
   public static void main(String[] args) {
       System.out.println(decodeRle("C3ecddf8"));
   }
}

تعليقات وثائق جافا

هذا نوع خاص من تعليقات Java يُستخدم لإنشاء صفحة وثائق. عادةً ما يكتب المطورون تعليقات التوثيق باستخدام Javadoc، وهو منشئ التوثيق لإنشاء وثائق API بتنسيق HTML من كود مصدر Java. يعد تنسيق المستندات الذي يستخدمه Javadoc هو المعيار الصناعي لتوثيق فئات Java وIDEs الأكثر شيوعًا مثل IntelliJ IDEA وEclipse، التي تنشئ Javadoc HTML تلقائيًا. تحتوي تعليقات وثائق Java على بناء الجملة أدناه:

/**
Some important Javadoc comments here
You don’t know it yet, but Javadoc rulez

@author  Java Developer
*/

فيما يلي مثال: إنه جزء من فئة Java Short . بالمناسبة، يمكنك الاطلاع على أي كود فئة Java من IDE الخاص بك (على سبيل المثال في IntelliJ IDEA من Windows، فقط اضغط على ctrl+LBM أو ctrl + b (في Windows) على اسم أي فئة أو طريقة).

package java.lang;

import jdk.internal.HotSpotIntrinsicCandidate;
import jdk.internal.misc.VM;

/**
* The {@code Short} class wraps a value of primitive type {@code
* short} in an object.  An object of type {@code Short} contains a
* single field whose type is {@code short}.
*
* <p>In addition, this class provides several methods for converting
* a {@code short} to a {@code String} and a {@code String} to a
* {@code short}, as well as other constants and methods useful when
* dealing with a {@code short}.
*
* @author  Nakul Saraiya
* @author  Joseph D. Darcy
* @see     java.lang.Number
* @since   1.1
*/
public final class Short extends Number implements Comparable<Short> {

   /**
    * A constant holding the minimum value a {@code short} can
    * have, -2<sup>15</sup>.
    */
   public static final short   MIN_VALUE = -32768;

   /**
    * A constant holding the maximum value a {@code short} can
    * have, 2<sup>15</sup>-1.
    */
   public static final short   MAX_VALUE = 32767;

   /**
    * The {@code Class} instance representing the primitive type
    * {@code short}.
    */
   @SuppressWarnings("unchecked")

إليك كود Java الخاص بالطريقة المعروفة والمحبوبة لدى جميع المبتدئين println() مع هذا التعليق:

/**
* Prints a String and then terminate the line.  This method behaves as
* though it invokes {@link #print(String)} and then
* {@link #println()}.
*
* @param x  The {@code String} to be printed.
*/
public void println(String x) {
   if (getClass() == PrintStream.class) {
       writeln(String.valueOf(x));
   } else {
       synchronized (this) {
           print(x);
           newLine();
       }
   }
}

يحتوي Javadoc على بعض علامات Javadoc الخاصة التي تحمل علامة @ والتي يمكنك رؤيتها في الكود أعلاه. مثال علامة Javadoc هو @author الذي يضيف اسم مؤلف الفئة. علامة Javadoc أخرى هي @since حيث تضيف تعليقًا يشير إلى أن هذه الفئة مستخدمة منذ الإصدار المحدد من Java. تتطلب كتابة مستندات Javadoc جيدة المعرفة والخبرة (والصبر!). يمكنك العثور على مزيد من المعلومات حول Javadoc في الوثائق الرسمية كيفية كتابة تعليقات المستند لأداة Javadoc .

ملاحظة: بعض الأمثلة على التعليقات المضحكة من الحياة الواقعية

/**
*Dear Maintainer
*
*Once you are done trying to 'optimize' this routine,
*and you have realized what a terrible mistake that was,
*please increment the following counter as a warning
*to the next guy.
*
*total_hours_wasted_here = 73
*/

Exception up = new Exception("Something is really wrong.");
throw up;  //ha ha

// When I wrote this, only God and I understood what I was doing
// Now, God only knows

// sometimes I believe compiler ignores all my comments

/**
Always returns true.
*/
public boolean isAvailable() {
return false;
}

لتعزيز ما تعلمته، نقترح عليك مشاهدة درس فيديو من دورة Java الخاصة بنا