
کامنت به توضیحاتی میگویند که برنامهنویس در لابهلای کدهایش به کار میبرد. رابرت مارتین میگوید کاری که میکنید را با کدتان توضیح دهید تا حداقل نیاز را به نوشتن کامنت داشته باشید؛ او لیستی از ویژگیهای کامنتهای بد و خوب را جمع کرده و من ترجمهای دستخورده از سخنانش را در اینجا آوردهام تا هم خود استفاده کنم و هم مورد استفادهی دیگران قرار بگیرد.
کامنتگذاشتن تنها به این سبب که فکر میکنید باید کامنتی گذاشته باشید یا اینکه پروسه به آن نیاز دارد! اگر کامنتی نوشتید، مطمئن شوید که بهترین کامنت ممکن است!
حشو در کامنت، یعنی نوشتن چیزی که نسبت به خودِ کد هیچ اطلاعات اضافیای به خواننده نمیدهد.
بعضیها هم بعد از ویرایش یک ماژول، خود را ملزم به اضافهکردن یک کامنت میکنند و مثل یک روزنامه یا گزارش کار هر تغییر و تحولی را در آن ثبت میکنند! به مثال زیر توجه کنید:
* 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);
شاید در زمانهای گذشته دلیل موجهی برای این کارها وجود داشت، اما امروزه با وجود سیستمهای کنترل کد و نسخه دیگر نیازی به این قیمه در ماست ریختنها نیست!
بعضی از کامنتها چیزی جز نویز نیستند! مثال زیر گویاتر از هر گفتاری است:
/** The day of the month. */ private int dayOfMonth;
نه، واقعا؟! بدون این کامنت، قادر به درک این Property نمیبودیم، خدا برنامهنویسش را بیامرزد!
زمانیکه بتوانیم به جای نوشتن کامنت، نام گویایی برای یک Function یا Variable بگذاریم، کامنتنوشتن اشتباه است!
حالات نادری وجود دارند که میتوان در آنها چیزی مانند مورد زیر را نوشت:
// Actions /////////////////////////
اما در حالت کلی باید از این کار خودداری نمود!
کامنتنویسی را با نوشتن انشا اشتباه نگیرید و از درج اطلاعات محرمانه یا تعریفکردن تاریخ که خوانندهی کد از خواندنشان بینیاز است، خودداری کنید!
توابع کوچک احتیاج زیادی به توضیحات ما ندارند؛ کافی است که نام مناسب و واضحی برایشان انتخاب کنیم و بقیهی کار را به خوانندهی کد بسپاریم!
گاهی برای حفظ حق کپیرایت، کامنتهایی مانند کامنت زیر را مینویسیم:
// 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.
هرچند که باید متدها و مشخصهها (Properties) خود را توضیح دهند، اما گاهی خوب است که اطلاعات مختصری را با یک کامنت به خواننده منتقل کنیم، برای مثال:
// Returns an instance of the Responder being tested. protected abstract Responder responderInstance();
گاهی برای دستیابی به یک هدف، کدی را مینویسیم و کسی که آن را ببیند، نمیتواند هدفی که پشت آن نهفته است را حدس بزند، برای همین از کامنت استفاده میکنیم:
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()); }
گاهی باید معنای یک آرگومان مبهم یا مقدار بازگشتی را به زبان آدمیزاد ترجمه کرد تا برای خواننده، خوانا شود.
assertTrue(a.compareTo(a) == 0); // a == a assertTrue(a.compareTo(b) != 0); // a != b assertTrue(ab.compareTo(ab) == 0); // ab == ab
یک تست را غیر فعال کردهایم، و روی آن مینویسیم: هشدار، بعد از اجرای این تست، بلایی بر سر سیستم میآید که از دست مدیر و تیم گزینهای جز درخواست پناهندگی برایتان نمیماند!
گاهی یادداشت میگذاریم تا بعداً کدی را تکمیل کنیم یا تغییر دهیم؛ این یادداشت را با TODO مینویسیم و خوشبختانه IDEهای خوب این TODOهای ما را ردگیری کرده و دیگر یادداشتهایمان گم نمیشوند!
ممکن است از یک کامنت برای تقویت و برجستهکردن اهمیت کاری که ظاهراً تفاوتی با روشهای دیگر ندارد استفاده کنیم.
ترجمهشده توسط «وبپژوه» با تصرف و اختصار از کتاب Clean Code (رابرت مارتین)