نظرات جاوا

نظرات بخشی از یک برنامه هستند که اجرا نمی شوند. کامپایلر به سادگی نظرات را نادیده می گیرد زیرا آنها برای آن در نظر گرفته نشده اند. آنها به زبان «انسانی» نوشته شده‌اند و برای توضیح برنامه، بخشی از برنامه، یک خط یا روش برای توسعه‌دهندگان یا افراد درگیر در توسعه طراحی شده‌اند. اغلب نظرات به زبان انگلیسی نوشته می شود، این یک نوع سنت است. در این مقاله قصد داریم در مورد نظرات در جاوا و نحوه استفاده صحیح از آنها برای سهولت در زندگی شما و هم تیمی هایتان صحبت کنیم.

نظرات جاوا: چرا آنها مهم هستند

آنها می گویند که برنامه نویسان برای اظهار نظر در مورد کد خود بسیار تنبل هستند. با این حال، این یک مهارت بسیار مهم است، بنابراین آن را دست کم نگیرید، حتی اگر تازه شروع به یادگیری جاوا کرده اید. کدهایی که به خوبی نظر داده می شوند بسیار ارزشمندتر از کدهای بدون نظر هستند زیرا نگهداری چنین برنامه ای بسیار آسان تر است. از آنجایی که پروژه‌های بزرگ اغلب به زبان جاوا نوشته می‌شوند، کامنت‌گذاری ماهرانه نیز سرعت توسعه را افزایش می‌دهد، زیرا برای یک برنامه‌نویس راحت‌تر است که با کد دیگران کار کند. نظرات به منظور:

• کد را درک کنید. مال شما یا شخص دیگری اگر به نظرتان می رسد که نیازی به رمزگشایی کد خود ندارید زیرا آن را نوشته اید، برنامه نسبتاً پیچیده ای را که یک ماه پیش یا حتی قبل از آن نوشتید باز کنید و سریع متوجه شوید که چه چیزی، کجا و چرا در ذهن دارید. از نظرات می توان برای توضیح منطق یک برنامه یا بلوک یک برنامه استفاده کرد و همچنین توصیه هایی را برای کسانی که بعداً با کد شما کار می کنند ارائه کرد. این نوع اظهار نظر را می توان توضیحی نامید.

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

• کنترل اشکالات و بهبود کد. کد یا کد مشکوک که نیاز به بهبود دارد همیشه می‌تواند نظر داده شود و بعداً دوباره مورد بازبینی قرار گیرد. اگر به ذهنتان می رسد که مشکل خاصی را می توان به روش دیگری حل کرد، اما اکنون برای آن وقت ندارید، این ایده را در کامنت بنویسید. در غیر این صورت، به احتمال زیاد، تحت فشار کد جدید، آن را فراموش خواهید کرد.

انواع نظرات در جاوا

علیرغم این واقعیت که می توانید هر چیزی و همه چیز را در نظرات بنویسید، انواع خاصی از نظرات در جاوا و قوانینی برای استفاده از آنها وجود دارد. در نظرات جاوا سرد باشد:

• نظرات تک خطی
• نظرات چند خطی
• نظرات مستندات

نظرات تک خطی

رایج ترین کامنت های جاوا کامنت های تک خطی هستند. برای نشان دادن چنین نظری کافی است قبل از متن یک اسلاید دوبل قرار دهید // . نظرات تک خطی فقط در ابتدای نظر علامت گذاری می شوند. نظر تا آخر خط ادامه دارد. نحو:

//here is a single line comment.

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

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
   }
}

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

نظرات چند خطی

گاهی اوقات یک خط برای نوشتن نظر جاوا کافی نیست. به عنوان مثال، باید نحوه عملکرد یک روش یا فرمول پیچیده ای را که در حال پیاده سازی آن هستید، توضیح دهید. در این حالت می توانید چندین کامنت تک خطی بنویسید، اما نوشتن نظرات به اصطلاح چند خطی منطقی تر خواهد بود. آنها در هر دو طرف با علامت /* */ مشخص شده اند . نحو کامنت های چند خطی:

/*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"));
   }
}

نظرات اسناد جاوا

این یک نوع خاص از نظرات جاوا است که برای ایجاد یک صفحه مستندات استفاده می شود. معمولاً توسعه دهندگان نظرات مستندات را با استفاده از Javadoc می نویسند، یک تولید کننده اسناد برای تولید اسناد API در قالب HTML از کد منبع جاوا. فرمت اسناد مورد استفاده توسط Javadoc استاندارد صنعتی برای مستندسازی کلاس های جاوا است و محبوب ترین IDE ها مانند IntelliJ IDEA و Eclipse به طور خودکار Javadoc HTML تولید می کنند. نظرات اسناد جاوا دارای نحو زیر هستند:

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

@author  Java Developer
*/

در اینجا یک مثال آورده شده است: این یک قطعه از کلاس Java Short است . به هر حال، می‌توانید به هر کد کلاس جاوا از IDE خود نگاه کنید (مثلاً در IntelliJ IDEA از ویندوز، کافیست ctrl+LBM یا ctrl + b (در ویندوز) را روی نام هر کلاس یا روشی فشار دهید).

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")

در اینجا کد جاوا متد معروف و محبوب همه مبتدیان 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 @ است زیرا یک نظر اضافه می کند که نشان می دهد این کلاس از نسخه مشخص شده جاوا استفاده می شود. نوشتن اسناد جاوادوک خوب نیاز به دانش و تجربه (و صبر!) دارد. می توانید اطلاعات بیشتر در مورد Javadoc را در اسناد رسمی نحوه نوشتن نظرات سند برای ابزار Javadoc بیابید .

PS چند نمونه نظرات خنده دار از زندگی واقعی

/**
*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;
}

برای تقویت آموخته هایتان، پیشنهاد می کنیم یک درس ویدیویی از دوره جاوا ما تماشا کنید