با اولین قسمت از سری آموزش کد نویسی تمیز در زبان سی شارپ از وب سایت پرووید در خدمت شما هستیم. در این قسمت در رابطه با اهمیت Comment ها و نکاتی که در رابطه با آنها باید بدانید صحبت خواهیم کرد. اغلب از Comment ها بعنوان یک ابزار بسیار مفید برای واضح تر کردن کاری که یک کد انجام می دهد استفاده می شود. اما نکته ی بسیار مهم اینست که اگر از نکات مهم استفاده کردن از Comment ها اطلاع نداشته باشید اتفاقاً آنها می توانند دردسرساز نیز بشوند. یکی از موضوعات بسیار بسیار معمول که توسط Comment ها اتفاق می افتد کاهش سطح خوانایی و یا Readability یک کد می باشد. در رابطه با تمامی این موارد در این مقاله صحبت خواهیم کرد.
یکی از نکات مهم در استفاده ی درست و صحیح از کامنت ها در زبان های برنامه نویسی اینست که نباید از آنها بعنوان یک ابزار برای توضیح دادن کد استفاده کنید. در واقع فرض بر این است که خواننده ی کد شما خود برنامه نویس است و برنامه نویسی را می داند. پس دیگر نیازی نیست که تک تک خطوط را به زبان فارسی و یا انگلیسی توضیح بدهید. کدی که در قسمت زیر نشان داده شده است مثالی از این موضوع است.
[c-sharp]
namespace CleanCSharp.Comments.Dirty {
// This defines a class called BasicCalculator
public class Calculator {
// Define default constructor
public Calculator() {}
// Define a method to add two numbers
public int AddTwoNumbers(int a, int b) {
// declare an int to hold result
int result;
// set result to sum of a and b
result = a + b;
// return the result to the caller
return result;
}
}
}
[/c-sharp]
دقت کنید که در این کد تمامی مراحل انجام کار در قالب Comment هایی توضیح داده شده است. در واقع برنامه نویسی که قصد خواندن این کد را دارد نه تنها باید این کد را خوانده و آنرا بفهمد، بلکه نیاز است که Comment هایی که بصورت انگلیسی نوشته شده اند را بخواند و آنها را درک کند. در استفاده کردن از Comment ها دقت کنید که آنها آنچه که کد انجام می دهد را توضیح ندهند. نکته ی مهمتر اینکه، در یکی از خطوط این کد یک خطا نیز وجود دارد. لطفاً به قسمت زیر دقت کنید.
[c-sharp]
// This defines a class called BasicCalculator
public class Calculator
[/c-sharp]
در این کد نه تنها از Comment ها بدرستی استفاده نشده، بلکه استفاده از آنها فریب دهنده هم هست. در واقع نام کلاس Calculator می باشد ولی در Comment مربوطه گفته شده است که این یک کلاس به نام BasicCalculator است. این موضوع یک حقیقت مهم دیگر را نیز نشان می دهد و آن اینکه Comment ها خیلی زود از کدی که آنها را توصیف می کنند عقب می افتند و اصطلاحاً ناهمگام می شوند. دلیل این موضوع اینست که با Refactor شدن و یا تغییر کردن یک کد، اغلب Comment های نوشته شده برای آن کد بروزرسانی نمی شوند و این باعث می شود که پس از مدتی Comment های نوشته شده با خود کد نوشته شده ناهمگام باشند.
پس بعنوان اولین قانون در رابطه با نوشتن Comment ها باید از نوشتن Comment های تکراری و یا Comment هایی که خود کد را توضیح می دهند جلوگیری کنید. اگر بخواهیم کدی را که در مثال بالا دیدیم تمیز کنیم، باید آنرا شبیه به قسمت زیر بنویسیم.
[c-sharp]
namespace CleanCSharp.Comments.Clean {
public class Calculator {
public int AddTwoNumbers(int a, int b) {
int result;
result = a + b;
return result;
}
}
}
[/c-sharp]
در این کد علاوه بر حذف شدن Comment هایی که کد را توضیح می دهند، تابع سازنده ای که بصورت اضافه تعریف شده بود نیز حذف گشته است. احتمالاً می دانید که اگر یک تابع سازنده بدون پارامتر و بدون بدنه در زبان برنامه نویسی سی شارپ در یک کلاس ایجاد کنید این تابع سازنده به هیچ دردی نمی خورد چرا که اگر وجود نیز نداشته باشد خود Compiler بصورت پیش فرض آنرا اضافه می کند. پس دیگر نیازی به نوشتن چنین تابع سازنده ای نداریم و آنرا در کلاس جدیدی که ایجاد کرده ایم حذف می کنیم.
یکی دیگر از اشتباهاتی که اغلب برنامه نویسان در استفاده کردن از Comment ها مرتکب می شوند نوشتن اطلاعات مربوط به تغییرات یک فایل در غالب Comment می باشد. کدی که در قسمت زیر مشاهده می کنید مثالی از این موضوع است.
[c-sharp]
namespace CleanCSharp.Comments.Dirty {
/* 10 Oct 2010 Sarah Smith – Created initial version
* Edited 20 Oct 2010 Amrit P – change calculation method
* Edited 20 Nov 2010 Jane Q – fix defect 4286
*/
public class MyClass {}
}
[/c-sharp]
در واقع با داشتن یک سیستم Source Control شبیه Git و یا TFS براحتی می توانیم زمان و تاریخ تغییر کردن فایلها را ثبت کنیم و دیگر نیازی نیست که آنها را در قالب Comment هایی به یک فایل اضافه کنیم. اگر از یک سیستم Source Control استفاده نمی شود حتماً باید این اتفاق بیافتد و اطلاعات مربوط به زمان و تاریخ تغییر کردن یک فایل بصورت Comment در یک فایل درج نشود. این نیز یکی دیگر از اشتباهات معمولی است که اغلب برنامه نویسان در استفاده کردن از Comment ها مرتکب می شوند.
یکی از معضلاتی که در استفاده کردن از Comment ها دیده می شود اینست که آنها را اغلب برای توصیف کردن کدهایی استفاده می کنیم که مبهم هستند. در واقع استفاده بیش از حد از Comment ها در یک فایل می تواند نمایانگر این باشد که خود کد نوشته شده در آن فایل دچار مشکل است و باید مورد Refactor قرار بگیرد. بعبارت دیگر، به شما توصیه می کنیم قبل از نوشتن Comment برای کدی که از قابلیت Readability و یا خوانایی کمی برخوردار است دست نگه دارید و ابتدا به استفاده از تکنیکهای Refactoring فکر کنید. اغلب می توان با پیاده سازی تکنیک های Refactoring قابلیت خوانایی و حتی قابل فهم بودن یک کد را افزایش داد و نیاز به نوشتن Comment ها را مرتفع کرد برای درک هرچه بهتر این موضوع کد زیر را ببینید.
[c-sharp]
namespace CleanCSharp.Comments.Dirty {
public class SimpleCalculator {
// Add two numbers together
public int Calculate(int a, int b) {
return a + b;
}
}
}
[/c-sharp]
در این مثال نام متد Calculate می باشد که به معنی محاسبه کردن است و سپس در قالب یک Comment گفته شده است که این متد به منظور جمع کردن دو عدد است که به عنوان ورودی دریافت می شوند. بهتر بود که بجای نوشتن این Comment نام این متد تغییر کند. همانطور که می دانید نامگذاری مناسب برای متدها یکی از تکنیک های Refactoring می باشد در واقع همواره باید سعی کرد که کدهای نوشته شده خود مستند و یا خود توصیف و اصطلاحاً Self-Documenting باشد. منظور از این قضیه اینست که، خود کد بگوید که قرار است چه کاری انجام بدهد و دیگر نیازی نباشد که در قالب یک Comment وظیفه ی آن کد مشخص و تعریف گردد. بنابراین، می توان کد بالا را شبیه به کدی که در قسمت زیر می بینید تغییر داد و از نوشتن Comment نیز جلوگیری کرد.
[c-sharp]
namespace CleanCSharp.Comments.Clean {
public class SimpleCalculator {
public int AddNumbers(int a, int b) {
return a + b;
}
}
}
[/c-sharp]
در این مثال با انتخاب یک نام مناسب برای متد دقیقا مشخص کرده ایم که وظیفه ی این متد چیست. حال دیگر نیازی نیست که با اضافه کردن یک Comment وظیفه ی این کد را مشخص کنیم.
اغلب دیده شده است که در کدهای موروثی و یا اططلاحاً Legacy Code ها که مربوط به سیستم های قدیمی می باشند تکه ای از کدها وجود دارند اما Comment شده اند. کدی که در قسمت زیر مشاهده می کنید این موضوع را نشان می دهد.
[c-sharp]
namespace CleanCSharp.Comments.Dirty {
public class AnotherSimpleCalculator {
public int AddNumbers(int a, int b) {
// a = a + 42;
return a + b;
}
}
}
[/c-sharp]
زمانی که یک برنامه نویس کد درون متد AddNumbers() را می خواند به خطی از کد برخورد می کند که آنجا وجود دارد اما Comment شده است. حال برنامه نویس با خود فکر می کند که منظور از این کد چه بوده است. آیا این کد بصورت اتفاقی Comment شده است. آیا باید از حالت Comment خارج بشود یا نه. در آموزشکدنویسی تمیز: نوشتن کد برای انسان ها از وب سایت پرووید مطرح کردیم که نام چنین کدهایی را اصطلاحاً کدهای زامبی و یا Zombie Code می نامیم. این موضوع باعث می شود که خواننده ی کد شما دچار ابهام بشود و جریان طبیعی خواندن کد دچار اختلال شده و قابلیت خوانایی کد کاهش پیدا می کند اغلب چنین کدهایی به این دلیل دخ می دهند که برنامه اول آنها را Comment کرده تا سپس آنها را پاک کند اما پاک کردن آنها را فراموش کند اما پاک کردن آنها را فراموش کرده است و یا به این فکر کرده است که احتمالاً در آینده آنها را نیاز خواهد داشت پس چه بهتر که آنها را پاک نکند و فقط آنها را Comment کند.
با استفاده کردن از یک سیستم Source Control مناسب دیگر نیازی به داشتن چنین کدهایی نیست؛ چرا که براحتی می توان نسخه های پیشین یک کد را بدست آورد. علاوه بر این، به شما توصیه می کنیم که حتماً و حتماً از نوشتن کدهایی به این شکل جلوگیری کنید. به عبارت دیگر، تکلیف کد را مشخص کنید که باید پاک شود و یا آنجا بماند و از داشتن کدهایی که به ظاهر حضور دارند اما واقعاً حضور ندارند جلوگیری کنید. چون همانطور که گفتیم اینگونه کدها قابلیت خوانایی کد را کاهش می دهند. این مورد نیز یکی دیگر از استفاده های ناصحیح از Comment ها را نشان می دهد. مطمئن هستم که تمامی ما برنامه نویسان چنین کدهایی را دیده ایم و یا ایجاد کرده ایم. اما، از این پس تلاش کنید که از نوشتن چنین کدهایی جلوگیری کرده و اگر با آنها روبرو می شوید تکلیف آنها را مشخص کنید.
احتمالاً Comment هایی که بصورت XML نوشته می شوند را تا بحال هم دیده اید و هم استفاده کرده اید. اصطلاحاً به این گونه Comment ها XML Documentation نیز می گویند. حال سوالی که مطرح است اینست که آیا نوشتن XML Documentation Comment ها همواره ضروری است یا نه؟ اینگونه از Comment ها نیز هر چند که می توانند قابلیت Readability یک کد را افزایش بدهند، اما اگر بطور نادرست مورد استفاده قرار بگیرند نتیجه ای که دریافت خواهید کرد عکس این موضوع خواهد بود. لطفاً به کدی که در قسمت زیر قرار داده شده است دقت کنید.
[c-sharp]
namespace CleanCSharp.Comments.Dirty {
///
< summary >
///
/// </summary>
public class BasicCalculator {
///
< summary >
/// Adds two numbers
/// </summary>
/// <param name="a"></param>
/// <param name="b"></param>
/// <returns></returns>
public int AddNumbers(int a, int b) {
return a + b;
}
}
}
[/c-sharp]
همانطور که در این مثال مشاهده می کنید تقریباً نیمی از خطوط نوشته شده با Comment های بی خود و بی فایده محصور شده اند. این موضوع نه تنها خود کد را مبهم تر می کند بلکه قابلیت خوانایی کد را نیز کاهش می دهد و پردازش شدن آن کد توسط برنامه نویس را نیز دچار اختلال می کند. حال می توانیم براحتی این کد را با حذف کردن Comment های XML شبیه به کد زیر کنیم و قابلیت خوانایی آنرا افزایش بدهیم.
[c-sharp]
namespace CleanCSharp.Comments.Clean {
public class BasicCalculator {
public int AddNumbers(int a, int b) {
return a + b;
}
}
}
[/c-sharp]
یکی از کاربردهای مهم XML Comment ها استفاده کردن از آنها در ساختن یک Public API می باشد. در واقع اگر قرار است که یک API طراحی بشود که بصورت عمومی توسط دیگر برنامه نویسان استفاده گردد می توان با استفاده از XML Comment ها در Type ها و Member هایی که بصورت Public تعریف شده اند؛ قابلیت استفاده از آن API را افزایش داد این موضوع به برنامه نویسان نیز بسیار کمک می کند. در غیر اینصورت؛ استفاده کردن از XML Comment ها عملاً بی فایده است.
به عنوان آخرین نکته در استفاده از Comment ها قصد داریم بگوئیم که از Comment ها فقط زمانی استفاده کنید که قصد کد بدرستی و به شفافیت قابل فهم نباشد. در واقع اگر خواننده و یا برنامه نویس دیگری که قرار است بر روی کد شما کار کند نتواند منظور از آن کد را براحتی درک کند می توانید با استفاده از Comment ها این موضوع را برای وی آسان تر کنید. در غیر اینصورت؛ استفاده از آنها بی فایده خواهد بود و می تواند مضر نیز باشد. قبلاً نیز اشاره کردیم که قبل از استفاده کردن از Comment ها برای مستندسازی یک کد ابتدا به ریفکتور کردن آن فکر کنید. اغلب با استفاده از تکنیکهای Refactoring می توانید قابلیت خوانایی یک کد را افزایش داده و نیاز به نوشتن Comment ها برای مستندسازی آن کد را مرتفع کنید.
امیدواریم که این آموزش از وبسایت پرووید نیز مورد توجه تمامی دوستان عزیز قرار گرفته باشد. از شما دعوت میکنیم که از دیگر آموزش های ما در رابطه با کدنویسی تمیز را نیز مطالعه کنید. لیست کامل این آموزش ها را می توانید در پست مربوط به آموزش اصول کدنویسی تمیز Clean Coding در سی شارپ مشاهده کنید.
دیدگاهها
0