اصول کامنت‌نویسی در زبان گو

تعریف #

«کامنت» به توضیحات‌ی گفته می‌شود که داخل کد، به‌قصد «یادآوری»، «جلب‌توجه مخاطب به موضوع‌(ها)ی خاص»، کمک به onboard شدن اعضاء جدید تیم و مانند اون نگارش می‌شود. در زبان گو، به شیوه‌های زیر کامنت می‌گذاریم:

• قرار دادن // در ابتدای سطر.

  1// defined to store multi string (see below why this is not a good comment)
  2var sliceVar []string
  

• قراردادن متن کامنت داخل یک بلوک که با */ شروع می‌شود و /* تمام می‌شود.

  1for index, row := range sliceVar {  
  2   row /* for loop lifetime */ = "new_val"  
  3   sliceVar[index] /* apply to sliceVar out of loop */ = "new_val"  
  4   fmt.Println(row) // hint to sliceVar large len  
  5}
  

دستور ‍gofmt کامنت‌ها را مانند سایر فرمت‌ها، مرتب می‌نماید. اما روش بهتر درصورت امکان، نظم آنها توسط خود توسعه‌دهنده جهت رعایت الگوها و ساختار خاص هر پروژه است.

1gofmt -w main.go

دیدگاه‌ها درباره «کامنت» #

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

کامنت؛ خوب، بد، زشت #

• در کدهایی که بارها نسخه‌های متفاوتی از آن ایجاد شده و در طول زمان، نیازمندی‌ها عوض شده، کیفیت، کارایی و سرعت اجرا بهبود پیدا کرده، «کامنت» گزارش «چرایی» کد هست برای این: نیاز/کیفیت/کارایی/سرعت اجرا، برای اینکه همه این‌ها رو دوباره تجربه نکنند ...
• یک کد خوب، هیچ نیازی به کامنت ندارد، به‌زبان‌دیگر، اگر نیاز می‌بینید که برای کدی «کامنت» بنویسید، احتمالاً، کد خوبی ننوشتید ...
• یک ساختار جدید، ناشناخته و احتمالاً حجیم، به‌قدر‌کافی ماهیتاً اینقدر پیچیدگی دارد که اضافه شدن، یک توضیح به زبان کاملاً انسانی (داخل زبان کامپایلر/مفسری برای زبان ماشین)، نه‌تنها باعث روشن‌تر شدن آن نمی‌شود بلکه مسئله‌ی فهم منظور نگارنده «کامنت» به مجموعه مسائل قبلی اضافه می‌گردد. هیچ‌چیز بیشتر از یک کد پیچیده با کلی «کامنت‌های» پیچیده برای مخاطبی که انتظار روشن بودن چرایی و چگونگی کد را دارد، عذاب‌آور نیست ...

همه این‌ها پاسخ‌های متفاوت‌ی است که توسعه‌دهندگان به موضوع «کامنت» می‌دهند. اما «اصولاً» کامنت پرفایده است یا بی‌فایده؟

آنالیز محصول و محیط توسعه #

وقتی در ارتباط با کامنت صحبت می‌کنیم این خیلی مهم است که ما به‌تنهایی مشغول توسعه یک محصول هستیم یا در یک دپارتمان کوچک یا در یک ابَرپروژه … آیا ما مجبور به تبعیت از یک‌سری دستورالعمل‌های کدنویسی هستیم یا می‌توانیم سلیقه‌شخصی خود را داشته باشیم؟ …

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

    نتیجه اینکه: ابتدا نیازمندی، توانایی و شرایط تیم/محصول را مشخص کنیم، و بعد تصمیم به چرایی و چگونگی کامنت‌نویسی اصولی بگیریم.

انواع کامنت #

• کامنت فایل/پکیج (Doc Comment) این‌نوع کامنت‌ها درباره «چیستی» کل فایل یا پکیج توضیح دارد.

 1// Copyright 2011 The Go Authors. All rights reserved.  
 2// Use of this source code is governed by a BSD-style  
 3// license that can be found in the LICENSE file.  
 4  
 5/*  
 6Package builtin provides documentation for Go's predeclared identifiers.  
 7The items documented here are not actually in package builtin  
 8but their descriptions here allow godoc to present documentation  
 9for the language's special identifiers.  
10*/  
11package builtin

مثال بالا از پکیج builtin درباره حق‌چاپ / تعریف اولیه پکیج و اینکه مستندات در godoc ارائه می‌شود، توضیح داده است.

• کامنت داخلی فانکشن/متد/بلوک/تایپ/متغیر/دستور و مانند آن (Ordinary Comments) این‌نوع کامنت درباره «چرایی» آن قسمتِ خاص اشاره دارد.

1// The delete built-in function deletes the element with the specified key  
2// (m[key]) from the map. If m is nil or there is no such element, delete  
3// is a no-op.  
4func delete(m map[Type]Type1, key Type)

در مثال بالا، توسط کامنت توضیح داده شده که وظیفه فانکشن-داخلی delete حذف المنت با کلید مشخص هست، و توضیح دقیق‌تر اینکه اگر المنت مربوط به کلید nil باشد یا وجود نداشته باشد، فانکشن delete هیچ عملیاتی انجام نمی‌دهد. (مثلاً خطا باز نمی‌گرداند − گزارش نمی‌کند و …)

اصول کامنت‌نویسی #

یک کامنت خوب:

1. توضیح واضحات را نمی‌دهد.
2. در حداقل مقدار «لازم» و «کافی» نگارش می‌شود.
3. بیشتر درباره «چیستی/چرایی» اشاره دارد و نه «چگونگی».
4. دارای یک الگو و دستورالعمل نگارشی واحد برای نظم و سرعت ارتباط مخاطب است.
5. وجودش آگاه‌کننده موضوع بااهمیت بالاست.
6. مربوط به موضوعی است که اکنون وجود دارد (بروزرسانی کامنت‌ها-حذف کامنت‌های اضافی)
7. ادبیات کامنت، بسته به تیم و دستورالعمل‌ها، بهتر است رسمی نگارش شود تا عمومی بماند. البته گاهی کمی شوخ‌طبعی هم اگر کنترل‌شده باشد، باعث انتقال‌مطلب بهتر می‌شود.
8. درصورت لازم بودن یک یا چند منبع مرتبط با کد، حاوی لینک url خواهد بود.

   1 	// flip the buffer for this connection if we need to drain it.  
   2 	// note that for a successful query (i.e. one where rows.next()  
   3 	// has been called until it returns false), `rows.mc` will be nil  
   4 	// by the time the user calls `(*Rows).Close`, so we won't reach this  
   5 	// see: https://github.com/golang/go/commit/651ddbdb5056ded455f47f9c494c67b389622a47  
   6 	mc.buf.flip()
   

به پرتگاه نزدیک می‌شوید! #

• زامبی کد: به کدی می‌گویند که به دلیل عدم کارایی، اصلاح با کد جدید، و یا مشابه این موارد، بجای «حذف»، «کامنت» می‌شوند.
• کامنت اسپاگتی کد: به کامنت‌های دنباله‌داری گفته می‌شود که برای توضیح یک کدی که ساختار منظم و مشخصی ندارد، نگارش می‌شود.
• یکی دیگر از استفاده‌های کامنت، وظیفه‌ی برنامه‌ریزی‌شده می‌باشد که اگر کنترل نشود، یکی دیگر از عذاب‌های عظیم خواهد بود.
• جای کلمات عبور و مقادیر امنیتی در کامنت نیست.
• اگر دائماً نیاز می‌بینید که در مراحل مختلف به همکاران بصورت کامنت «هشدار» بنویسید، شاید باید به‌فکر اصلاح معماری نرم‌افزار باشید.
• کامنت‌های شما، نباید تبدیل به «نویز» درکدنویسی دیگران شود. تعدد کامنت‌ها کد را تبدیل به کد کثیف می‌کند که خوانایی ضعیفی خواهد داشت.
• کامنت، جای دردل کردن، شکایت از مدیرپروژه، تعریف از خود و گفتگو نیست.