نظرات در مورد کد مربوط به گذشته است
آیا هر بار که با روشی یا عملکردی روبرو می شویم ، کمی کوچک نمی شویم یا کلاسي که بالاي آن نظر طولاني و آزاد داشته باشد؟ خوب ، دلیل آن این است که بیشتر آن نظرات طولانی مدت عبارتند از:
- علامت بهم ریختگی کد زیر آن است
- هیچ ارتباطی با کد زیر ندارید (از همگام سازی برخوردار نیست ، به خوبی نگهداری نمی شود ) ؛
- یک نسخه دقیق از کد زیر آن ، فقط با عبارت "طبیعی تر" (وقت گذران وقت) نوشته شده است ؛
نظرات خیلی زود از رده خارج می شوند! برای حفظ آنها کار سختی است ، نوشتن آنها کار سختی است و شما با اجازه دادن به آنها خوانایی (و در نتیجه ماندگاری) را دلسرد می کنید!
اگر برای درک کد شما نیاز به خواندن نظر شما دارم ، کد شما مشکلی دارد.
بنابراین چه گزینه ای وجود دارد؟ گزینه دیگر ارتقا to خوانایی است. کد باید خود مستند باشد. هنگام استفاده از سازه های سطح بالا به زبان برنامه نویسی هنگام ایجاد یک برنامه یا ویژگی یا رفع اشکال ، به طور غیر قابل مقایسه ای بهتر است که از قوانین طبیعی پیروی کنید.
هنگام نوشتن کد ، یک دستورالعمل محاسباتی ، نه تنها مسئول انتقال واضح این دستورالعمل به رایانه بلکه مسئول انتقال این دستورالعمل به نگهدارنده های فعلی / آینده است. ما دیگر در حباب نیستیم ، جهانی شدن امری است که بدون ارتباطات مناسب و در سطح کد ، امکان رشد (به صورت جداگانه و به صورت تیمی / سازمانی) وجود ندارد.
و البته برخی موارد استثنا نیز وجود دارد. [19659013] به عنوان مثال ، یک نظر می تواند مفید باشد اگر انتخاب یک الگوریتم را توضیح دهد ، دلیل اصلی این اجرای خاص الگوریتم ، اینکه چرا این تصمیم مهم است.
به طور کلی ، نظرات می توانند به یکی از دو سوال پاسخ دهند: "چه ؟ " و چرا؟". "کد زیر چه کاری انجام می دهد؟" و "چرا کد زیر وجود دارد؟". نظراتی که به "چرا" پاسخ می دهند سوال قابل قبول است ، نظراتی که پاسخ می دهند "چه؟"
باز هم ، هنگام تصمیم گیری به بهترین قضاوت خود مراجعه کنید.
اسناد API و به طور یکسان چطور؟
اسناد API یک ضرورت است! بدون اسناد و مدارک نمی توانید API داشته باشید و حتی در این حالت هرگز نباید خودتان نظر بنویسید. مستندات API باید براساس کد شما به صورت خودکار تولید شود.
شما باید بتوانید اسناد سبک Swagger را بدون نوشتن یک خط از نظر خود ایجاد کنید.
راه اندازی کامل نسل API: کدهای قابل خواندن با زبان دقیق تایپ شده . ژنراتورهای مدرن باید بتوانند نام متغیر / متد / توابع نوشته شده با CamelCase یا snake_case را تجزیه و ترجمه کنند و آن را به مستندات قابل خواندن ترجمه کنند (مشابه نحوه کار GitHub با نام شاخه در هنگام ایجاد روابط عمومی با چندین تعهد).
در پایان.
] با کد خود ارتباط برقرار کنید (نه نظرات) ، با بررسی کد ارتباط برقرار کنید ، منابع داخلی (فردی) را که برای نظر اختصاص داده اید سرمایه گذاری کنید تا خوانایی کد را بهبود بخشد. این سرمایه گذاری در آینده نتیجه خوبی خواهد داشت.
P.S.
آیا تا به حال پست شغلی را دیده اید که در آن "نوشتن کد خوب با نظر" در بخش مسئولیت های شغلی نوشته شده باشد؟ خوب ، این یک پرچم قرمز است! شما خوش آمدید.
PPS
