از کامنت بد تا کامنت خوب

"بگذار توضیح در کد تو باشد، نه در کامنتی که به کار می‌بری"

کامنت به توضیحاتی می‌گویند که برنامه‌نویس در لابه‌لای کدهایش به کار می‌برد. رابرت مارتین می‌گوید کاری که می‌کنید را با کدتان توضیح دهید تا حداقل نیاز را به نوشتن کامنت داشته باشید؛ او لیستی از ویژگی‌های کامنت‌های بد و خوب را جمع کرده و من ترجمه‌ای دست‌خورده از سخنانش را در اینجا آورده‌ام تا هم خود استفاده کنم و هم مورد استفاده‌ی دیگران قرار بگیرد.


کامنت بد یعنی چه؟

1) مزخرف

کامنت‌گذاشتن تنها به این سبب که فکر می‌کنید باید کامنتی گذاشته باشید یا اینکه پروسه به آن نیاز دارد! اگر کامنتی نوشتید، مطمئن شوید که بهترین کامنت ممکن است!

2) حشو

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

3) روزنامه‌نگارانه

بعضی‌ها هم بعد از ویرایش یک ماژول، خود را ملزم به اضافه‌کردن یک کامنت می‌کنند و مثل یک روزنامه یا گزارش کار هر تغییر و تحولی را در آن ثبت می‌کنند! به مثال زیر توجه کنید:

* Changes (from 11-Oct-2001)
* --------------------------
* 27-Aug-2002 : Fixed bug in addMonths() method, thanks to N???levka Petr (DG);
* 03-Oct-2002 : Fixed errors reported by Checkstyle (DG);
* 13-Mar-2003 : Implemented Serializable (DG);
* 29-May-2003 : Fixed bug in addMonths method (DG);
* 04-Sep-2003 : Implemented Comparable.  Updated the isInRange javadocs (DG);
* 05-Jan-2005 : Fixed bug in addYears() method (1096282) (DG);

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

3) نویز

بعضی از کامنت‌ها چیزی جز نویز نیستند! مثال زیر گویاتر از هر گفتاری است:

/** The day of the month. */
private int dayOfMonth;

نه، واقعا؟! بدون این کامنت، قادر به درک این Property نمی‌بودیم، خدا برنامه‌نویسش را بیامرزد!

4) چرا متغیر و تابع نه؟!

زمانی‌که بتوانیم به جای نوشتن کامنت، نام گویایی برای یک Function یا Variable بگذاریم، کامنت‌نوشتن اشتباه است!

5) تیتر

حالات نادری وجود دارند که می‌توان در آنها چیزی مانند مورد زیر را نوشت:

// Actions /////////////////////////

اما در حالت کلی باید از این کار خودداری نمود!

6) اطلاعات خیلی زیاد!

کامنت‌نویسی را با نوشتن انشا اشتباه نگیرید و از درج اطلاعات محرمانه یا تعریف‌کردن تاریخ که خواننده‌ی کد از خواندنشان بی‌نیاز است، خودداری کنید!

7) سربرگ توابع

توابع کوچک احتیاج زیادی به توضیحات ما ندارند؛ کافی است که نام مناسب و واضحی برایشان انتخاب کنیم و بقیه‌ی کار را به خواننده‌ی کد بسپاریم!


کامنت خوب یعنی چه؟

1) کامنت‌های قانونی

گاهی برای حفظ حق کپی‌رایت، کامنت‌هایی مانند کامنت زیر را می‌نویسیم:

// Copyright (C) 2003,2004,2005 by Object Mentor, Inc. All rights reserved.
// Released under the terms of the GNU General Public License version 2 or later.

2) کامنت‌های توضیحی

هرچند که باید متدها و مشخصه‌ها (Properties) خود را توضیح دهند، اما گاهی خوب است که اطلاعات مختصری را با یک کامنت به خواننده منتقل کنیم، برای مثال:

// Returns an instance of the Responder being tested.
protected abstract Responder responderInstance();

3) توضیح هدف

گاهی برای دستیابی به یک هدف، کدی را می‌نویسیم و کسی که آن را ببیند، نمی‌تواند هدفی که پشت آن نهفته است را حدس بزند، برای همین از کامنت استفاده می‌کنیم:

public void testConcurrentAddWidgets() throws Exception {
   WidgetBuilder widgetBuilder = new WidgetBuilder(new Class[]{BoldWidget.class});
   String text = "'''bold text'''"
   ParentWidget parent = new BoldWidget(new MockWidgetRoot(), "'''bold text'''");
   AtomicBoolean failFlag = new AtomicBoolean();
   failFlag.set(false);
   // This is our best attempt to get a race condition 
   // by creating large number of threads.
   for (int i = 0; i < 25000; i++) {
      WidgetBuilderThread widgetBuilderThread = new WidgetBuilderThread(widgetBuilder, text, parent, failFlag);
      Thread thread = new Thread(widgetBuilderThread);
      thread.start();
      }
   assertEquals(false, failFlag.get());
}

4) واضح‌سازی

گاهی باید معنای یک آرگومان مبهم یا مقدار بازگشتی را به زبان آدمیزاد ترجمه کرد تا برای خواننده، خوانا شود.

assertTrue(a.compareTo(a) == 0);    // a == a
assertTrue(a.compareTo(b) != 0);    // a != b
assertTrue(ab.compareTo(ab) == 0);  // ab == ab

5) هشدار نسبت به عواقب ناگوار

یک تست را غیر فعال کرده‌ایم، و روی آن می‌نویسیم: هشدار، بعد از اجرای این تست، بلایی بر سر سیستم می‌آید که از دست مدیر و تیم گزینه‌ای جز درخواست پناهندگی برایتان نمی‌ماند!

6) کامنت TODO

گاهی یادداشت می‌گذاریم تا بعداً کدی را تکمیل کنیم یا تغییر دهیم؛ این یادداشت را با TODO می‌نویسیم و خوشبختانه IDEهای خوب این TODOهای ما را ردگیری کرده و دیگر یادداشت‌هایمان گم نمی‌شوند!

7) تقویت

ممکن است از یک کامنت برای تقویت و برجسته‌کردن اهمیت کاری که ظاهراً تفاوتی با روش‌های دیگر ندارد استفاده کنیم.


ترجمه‌شده توسط «وب‌پژوه» با تصرف و اختصار از کتاب Clean Code (رابرت مارتین)