اصول کامنت نویسی
یک کامنت خوب:
1. توضیح واضحات را نمیدهد.
2. در حداقل مقدار «لازم» و «کافی» نگارش میشود.
3. بیشتر درباره «چیستی/چرایی» اشاره دارد و نه «چگونگی».
4. دارای یک الگو و دستورالعمل نگارشی واحد برای نظم و سرعت ارتباط مخاطب است.
5. وجودش آگاهکننده موضوع بااهمیت بالاست.
6. مربوط به موضوعی است که اکنون وجود دارد (بروزرسانی کامنتها-حذف کامنتهای اضافی)
7. ادبیات کامنت، بسته به تیم و دستورالعملها، بهتر است رسمی نگارش شود تا عمومی بماند. البته گاهی کمی شوخطبعی هم اگر کنترلشده باشد، باعث انتقالمطلب بهتر میشود.
8. درصورت لازم بودن یک یا چند منبع مرتبط با کد، حاوی لینک url خواهد بود.
منبع
#Comment
@Syntax_fa
یک کامنت خوب:
1. توضیح واضحات را نمیدهد.
2. در حداقل مقدار «لازم» و «کافی» نگارش میشود.
3. بیشتر درباره «چیستی/چرایی» اشاره دارد و نه «چگونگی».
4. دارای یک الگو و دستورالعمل نگارشی واحد برای نظم و سرعت ارتباط مخاطب است.
5. وجودش آگاهکننده موضوع بااهمیت بالاست.
6. مربوط به موضوعی است که اکنون وجود دارد (بروزرسانی کامنتها-حذف کامنتهای اضافی)
7. ادبیات کامنت، بسته به تیم و دستورالعملها، بهتر است رسمی نگارش شود تا عمومی بماند. البته گاهی کمی شوخطبعی هم اگر کنترلشده باشد، باعث انتقالمطلب بهتر میشود.
8. درصورت لازم بودن یک یا چند منبع مرتبط با کد، حاوی لینک url خواهد بود.
منبع
#Comment
@Syntax_fa
👍9👎1
دیدگاه های مختلف درباره «کامنت»
با توجه به این موضوع که در جوامعتخصصی توسعه نرمافزار، درارتباط با اصل وجود کامنت، مزایا/معایب و چگونگی استفاده از آن، مطالب گوناگون و بعضاً متضادی (حتی از جانب متخصصین) وجود دارد، بیایم برخی از این دیدگاه هارو با هم مرور کنیم.
کامنت؛ خوب، بد، زشت
در کدهایی که بارها نسخههای متفاوتی از آن ایجاد شده و در طول زمان، نیازمندیها عوض شده، کیفیت، کارایی و سرعت اجرا بهبود پیدا کرده، «کامنت» گزارش «چرایی» کد هست برای این: نیاز/کیفیت/کارایی/سرعت اجرا، برای اینکه همه اینها رو دوباره تجربه نکنند ...
یک کد خوب، هیچ نیازی به کامنت ندارد، بهزباندیگر، اگر نیاز میبینید که برای کدی «کامنت» بنویسید، احتمالاً، کد خوبی ننوشتید ...
یک ساختار جدید، ناشناخته و احتمالاً حجیم، بهقدرکافی ماهیتاً اینقدر پیچیدگی دارد که اضافه شدن، یک توضیح به زبان کاملاً انسانی (داخل زبان کامپایلر/مفسری برای زبان ماشین)، نهتنها باعث روشنتر شدن آن نمیشود بلکه مسئلهی فهم منظور نگارنده «کامنت» به مجموعه مسائل قبلی اضافه میگردد. هیچچیز بیشتر از یک کد پیچیده با کلی «کامنتهای» پیچیده برای مخاطبی که انتظار روشن بودن چرایی و چگونگی کد را دارد، عذابآور نیست ...
#Comment
@Syntax_fa
با توجه به این موضوع که در جوامعتخصصی توسعه نرمافزار، درارتباط با اصل وجود کامنت، مزایا/معایب و چگونگی استفاده از آن، مطالب گوناگون و بعضاً متضادی (حتی از جانب متخصصین) وجود دارد، بیایم برخی از این دیدگاه هارو با هم مرور کنیم.
کامنت؛ خوب، بد، زشت
در کدهایی که بارها نسخههای متفاوتی از آن ایجاد شده و در طول زمان، نیازمندیها عوض شده، کیفیت، کارایی و سرعت اجرا بهبود پیدا کرده، «کامنت» گزارش «چرایی» کد هست برای این: نیاز/کیفیت/کارایی/سرعت اجرا، برای اینکه همه اینها رو دوباره تجربه نکنند ...
یک کد خوب، هیچ نیازی به کامنت ندارد، بهزباندیگر، اگر نیاز میبینید که برای کدی «کامنت» بنویسید، احتمالاً، کد خوبی ننوشتید ...
یک ساختار جدید، ناشناخته و احتمالاً حجیم، بهقدرکافی ماهیتاً اینقدر پیچیدگی دارد که اضافه شدن، یک توضیح به زبان کاملاً انسانی (داخل زبان کامپایلر/مفسری برای زبان ماشین)، نهتنها باعث روشنتر شدن آن نمیشود بلکه مسئلهی فهم منظور نگارنده «کامنت» به مجموعه مسائل قبلی اضافه میگردد. هیچچیز بیشتر از یک کد پیچیده با کلی «کامنتهای» پیچیده برای مخاطبی که انتظار روشن بودن چرایی و چگونگی کد را دارد، عذابآور نیست ...
#Comment
@Syntax_fa
👍6
به پرتگاه نزدیک میشوید!
زامبی کد: به کدی میگویند که به دلیل عدم کارایی، اصلاح با کد جدید، و یا مشابه این موارد، بجای «حذف»، «کامنت» میشوند.
کامنت اسپاگتی کد: به کامنتهای دنبالهداری گفته میشود که برای توضیح یک کدی که ساختار منظم و مشخصی ندارد، نگارش میشود.
یکی دیگر از استفادههای کامنت، وظیفهی برنامهریزیشده میباشد که اگر کنترل نشود، یکی دیگر از عذابهای عظیم خواهد بود.
جای کلمات عبور و مقادیر امنیتی در کامنت نیست.
اگر دائماً نیاز میبینید که در مراحل مختلف به همکاران بصورت کامنت «هشدار» بنویسید، شاید باید بهفکر اصلاح معماری نرمافزار باشید.
کامنتهای شما، نباید تبدیل به «نویز» درکدنویسی دیگران شود. تعدد کامنتها کد را تبدیل به کد کثیف میکند که خوانایی ضعیفی خواهد داشت.
کامنت، جای دردل کردن، شکایت از مدیرپروژه، تعریف از خود و گفتگو نیست.
#Comment
@Syntax_fa
زامبی کد: به کدی میگویند که به دلیل عدم کارایی، اصلاح با کد جدید، و یا مشابه این موارد، بجای «حذف»، «کامنت» میشوند.
کامنت اسپاگتی کد: به کامنتهای دنبالهداری گفته میشود که برای توضیح یک کدی که ساختار منظم و مشخصی ندارد، نگارش میشود.
یکی دیگر از استفادههای کامنت، وظیفهی برنامهریزیشده میباشد که اگر کنترل نشود، یکی دیگر از عذابهای عظیم خواهد بود.
جای کلمات عبور و مقادیر امنیتی در کامنت نیست.
اگر دائماً نیاز میبینید که در مراحل مختلف به همکاران بصورت کامنت «هشدار» بنویسید، شاید باید بهفکر اصلاح معماری نرمافزار باشید.
کامنتهای شما، نباید تبدیل به «نویز» درکدنویسی دیگران شود. تعدد کامنتها کد را تبدیل به کد کثیف میکند که خوانایی ضعیفی خواهد داشت.
کامنت، جای دردل کردن، شکایت از مدیرپروژه، تعریف از خود و گفتگو نیست.
#Comment
@Syntax_fa
👍10