Business Intelligence Developers Association Registered

پادکست

پادکست31: بررسی فصل 4 تا 7 کتاب کد تمیز

bidar.ca آوریل 13, 2022

Radio.BIDAR.ca

00:00 /

گفتگوی گروهی از متخصصان صنعت نرم افزار در کانادا: طلیعه دوانی، آرش گودرزی، ،یوسف عمادی، محمد نادی، مهدی شکوهی، شریف یزدیان و محمد امین فرد

در این پادکست خلاصه ای از فصل ها
4- Comments
5- Formatting
6- Objects and Data Structures
7- Error Handling
کتاب کد تمیز یا Clean code رابرت مارتین ارائه شد

یادداشت های بخش کامنت کتاب clean code

صفحه 55

یکی از دلایلی که کامنت می نویسم کد نویسی بده

مثلا یک ماژول می نویسیم و میدونیم که باعث سردرگمی و به هم ریختگی میشه. میدونیم که کثیف کاریه

حالا مثلا میخوایم براش راه حل پیدا کنیم، کامنت می نویسیم

نه !

بهتره کد رو تمیزش کنید

یک کد تمیز و خوانا با کامنت های کم، خیلی بهتر از درهم و برهم و پیچیده نوشتن با کامنت های زیاده

خودتون رو تو کدتون نشون بدید ( مثل دست خط ) Explain yourself in code

کامنت های خوب :

با این حال بعضی از کامنت ها ضروری یا سودمندند

کامنت های قانونی:

بعضی از کامنت ها مثل استاندارد شرح کپی رایت یا مالکیت

که خیلی خوشحالم خیلی از IDE ها کامنت ها رو اتوماتیک collapse می کنند و مخفی میشه

کامنت های اطلاع رسانی:

مثلا اینکه خروجی تابع چی هست

کامنت هایی که قصدمون رو توضیح میدیم Explanation of Intent:

مثلا وقتی دو تا آبجکت رو مقایسه می کنیم ، نویسنده تصمیم گرفته که آبجکت ها رو مرتب سازی

شفاف سازی:

برای دقیق تر شدن چیزی می تونیم توضیح بدیم

هشدار عواقب :

بعضی مواقع که میخواهیم ریسک یک چیزی را اطلاع بدیم

مثلا اگر با این شرایط خاص برنامه اجرا بشه ممکنه چه اتفاقی بیفته

کامنت های TODO

تقویتی

javadocs در API های عمومی

کامنت های بد :

ناواضح و زمزمه ای: درصورتی که کامنت ها باید واضح و شفاف باشند

اضافی و زاید: مثال هایی از کامنت که دقیقا همون کد را تکرار کرده ، در تامکت این کامنت های اضافی خیلی اذیت کننده هستند

Misleadingگمراه کننده: : this.close true;

اجباری: خیلی احمقانه است که هر تابع باید javadoc داشته باشند یا هر متغیر یک کامنت داشته باشه

ژورنالی : بعضی وقت ها افراد برای هر تغییری یک توضیحی را در کامنت می نویسند ، تاریخچه تغییرات در کد رو می نویسند

نویز: بعضی وقت ها می بینید کامنت مثل یک نویز هست ، مثلا

نویز وحشتناک: کپی پیست از یک کامنت دیگه

از کامنت ها استفاده نکنید وقتی میتونید از یک تابع یا متغیر استفاده کنید

موقعیت نما ها Position Markers :

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

Brace Comments – کامنت انتهای براکت

Attributions and Bylines – سیستم های سورس کنترل همه چیز رو حفظ می کنند که چه زمانی و چه کسی چه چیزی رو تغییر داده یا اضافه کرده

بنابراین نیاز نیست بنویسید

Commented-Out Code – کامنت کردن تکه های از کد

کنید این کار رو

میخواید به عنوان چرک نویس استفاده کنید ؟

سیستم های سورس کنترل ، سورس قبلی رو براتون حفظ می کنند ، قول میدم نیازی که چرک نویس داخل کد ندارید

HTML Comments – قراردادن کد های html در کامنت ها یک کار زشته ، اگر قرار باشه با ابزاری مثل javadoc متن کامنت ها شبیه یک صفحه وب تزیین بشه ، اون برنامه باید اون کار رو بکنه ، نه اینکه برنامه نویس کامنت رو تزیین کنه

Nonlocal Information اگر کامنتی را الزامیه ، در همون محدوده نزدیک کد بنویسید ، اطلاعات را به صورت گلوبال ننویسید و یا اینکه بعد از تغییرات کد مراقب باشید که کامنت خیلی از کد فاصله نگیره

Too Much Information – کامنت ها رو به عنوان داستان تاریخی یا ، داستان غیر مرتبط خیلی جزیی تعریف نکنید

Inobvious Connection.ارتباط نامشخص : کامنت و کد باید ارتباط داشته باشند ، اگر در کد مشکلی هم برخوردید ، لااقل در کامنت بنویسید که چه مشکلی بوده، نه اینکه فکر کنه اصلا این کامنت ربطی به این کد نداره

Function Headers : هدر های تابع نیازی نداره که خیلی زیاد شرح داده بشه

Javadocs in Nonpublic Code

میدونیم که کامنت ها در کد های API عمومی javadoc خیلی کاربردی هستند، ولی وقتی کد رو در یک سیستم داخلی استفاده می کنید چرا کامنت های javadocs براش می نویسید؟