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

یکی از روش هایی که کمک می‌کنه متن خطای خوبی بنویسید این هست که متن ارور شما به شکلی نوشته بشه که بتونه جواب این سوال ها رو بده :

چه کسی باعث شده این ارور بوجود بیاد؟

به عنوان مثال اگر یک وبسایت می‌سازید و ارور 500 اتفاق می‌افته توی متن ارور بگید که مشکل از سمت سرور هست یا اگر ارور 400 اتفاق افتاده بگید که مشکل از طرف کاربر هست. همین مورد ساده کمک می‌کنه که کاربر تا حدودی بدونه که قدم بعدی برای برطرف کردن مشکل چی هست و باید از چه جایی کار رو ادامه بده.

چرا این ارور بوجود اومده؟

توضیح کوتاهی از دلیل بوجود اومدن ارور بدید. مثلا اگر ارور 404 اتفاق افتاده می‌تونید توضیح بدید که آدرسی که کاربر وارد کرده پیدا نشده و شاید این مشکل بخاطر این هست که url رو درست وارد نکرده.

چه موقع این مشکل برطرف می‌شه؟

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

کاربر چطوری می‌تونه مشکل رو برطرف کنه؟

فرض کنید که کاربر ارور 404 گرفته. می‌تونید داخل متن ارور چنتا راه حل رو پیشنهاد بدید مثلا بگید که URL رو چک کنه و اگر مشکل حل نشد از امکان search استفاده کنه و اگر باز هم مشکل برطرف نشد راه برقراری ارتباط با پشتیبان رو نشون بدید.

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

کامنت نوشتن داخل کد همیشه یکی از موضوعاتی بوده که در عین سادگی پیچیدگی های خودش رو هم داشته. بعضیا با نوشتن کامنت موافق هستن بعضیا هم مخالف و در کل نظرات مختلفی در مورد نوشتن کامنت وجود داره.
در ادامه لیستی از قواعدی که موقع نوشتن کامنت به ما کمک می‌کنه رو به همراه مثال کوتاه توضیح دادم.

۱ ) کامنت نباید کد رو تکرار کند

کسی که کد رو میخونه مسلما درکی از اصول برنامه نویسی داره و کامنت شما نباید همون کدی که نوشتید رو تکرار کنه. چرا که به مرور زمان مثل یک عادت میشه و بعد از مدتی یک مجموعه کد کثیف دارید که پر شده از کامنت هایی که هیچ کمکی نمی‌کنند. به عنوان مثال :

i += 1; // add one to i

۲ ) کامنت خوب کد بد رو توجیه نمی‌کنه

یکی از اصول کد تمیز نوشتن کد هایی هست که self-documenting هستند. یعنی موقع خوندن کد متوجه می‌شید که چه اتفاقی در حال افتادن هست و از اون طرف دیگه نیاز به توضیح دادن کد خودتون ندارید. به عنوان مثال داخل کد زیر اگر اسم خوبی برای متغیر انتخاب کنیم هم کد خوانا تری داریم و هم دیگه کامنت اضافه رو نیاز نداریم.

int a = 22; // a is age

۳ ) اگر کامنت واضحی برای کدتون نمی‌تونید بنویسید احتمالا مشکلی داخل کد وجود داره

فرض کنید یک کد پیچیده رو از جایی کپی می‌کنید یا از دوستتون می‌خواید که براتون بنویسه. از اونجایی که اون کد پیچیده هست و شما هم خوب متوجه اش نشدید و فقط کارتون رو راه انداختید پس یک کامنت نا مفهوم بالای کدتون می‌نویسید و ادامه زندگی رو از سر می‌گیرید.
کار خوبی که اینجور مواقع میشه کرد این هست که سعی کنید کد رو متوجه بشید یا اگر امکانش هست اون رو به شکل ساده تری بنویسید که خوانا و قابل درک باشه.

۴ ) کامنت باید ابهام رو از بین ببره، نه اینکه خودش باعث ابهام بشه

اگر کامنت شما ابهام کدتون رو از بین نمی‌بره و خودش هم باعث ابهام میشه پس بهتره که اصلا کامنت ننویسید. یادتون باشه که کد بدون کامنت، بهتره از کدی که کامنت بد داره.

۵ ) کد های غیر مصطلح (unidiomatic) رو در کامنت توضیح بدید

گاهی وقت ها کد هایی هستند که اگر دیگران اون ها رو ببینن احتمالا میگن که این کد اضافه هست. یا این کد کار خاصی رو انجام نمیده. اینجور وقت ها بهترین کار این هست که با یک کامنت کوتاه و ساده کد رو توضیح بدین و جلوی این مشکل رو بگیرید.

۶ ) اگر کدی رو از جایی کپی کردید داخل کامنت ها به منبع اصلی لینک بدید

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

۷ ) اگر لینک دادن به منبع های خارجی مفید هست توی کامنت ها این کار رو بکنید

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

۸ ) وقتی باگی رو برطرف می‌کنید کامنت بزارید

نوشتن کامنت فقط مربوط به زمانی که کد رو می‌نویسیم نیست و حتی زمانی که یک باگ رو حل می‌کنیم یک کامنت کوتاه می‌تونه مشخص بکنه که قطعه کد ما توی چه شرایطی اجرا می‌شه و چه مشکلی رو حل می‌کنه. اگر نیاز هم به توضیح دقیق تر یا طولانی تر هست می‌تونیم از روش های ۶ و ۷ استفاده کنیم.

۹ ) اگر پیاده سازی قسمتی از کد هنوز انجام نشده، اون قسمت رو با کامنت مشخص کنید

اگر قسمتی از کد به عنوان یک بدهی فنی هست و بعدا باید کامل بشه یا به هر دلیل دیگه ای الان نمی‌تونید تکمیلش کنید کافیه یک TODO رو کامنت کنید و حتی بهتره که یک ایشو برای این قسمت از کد تعریف کنید و لینک ایشو رو داخل کامنت ها قرار بدید.

مورد هایی که تا اینجا خوندید رو از این لینک گذاشتم. اگر خواستید حتما به لینک اصلی هم سر بزنید. نکته ای که خوبه بهش دقت کنیم این هست که توی استفاده از کامنت زیاده روی نکنیم. تکنیک هایی مثل نوشتن کد تمیز یا نوشتن تست هایی که حالت های مختلف رو بررسی می‌کنه باعث می‌شه که کمتر از کامنت استفاده کنیم. نه اینکه کامنت چیز بدی باشه اما اعتدال توی استفاده از کامنت رو باید در نظر داشته باشیم.