نویسنده: WKFGo Editorial · ·
استاندارد کدنویسی چیست؟
استاندارد کدنویسی مجموعه قواعدی است که خوانایی، ایمنی و نگه‌داری کد را در تیم قابل پیش‌بینی می‌کند. بخش قطعی آن مانند قالب‌بندی، import و خطاهای شناخته‌شده باید با formatter، linter و CI کنترل شود؛ بخش نیازمند قضاوت مانند طراحی API، مرز ماژول و نام‌گذاری دامنه در بازبینی انسانی بررسی می‌شود.
سندی که فقط در onboarding دیده شود استاندارد اجرایی نیست. قاعده باید هنگام شروع تسک، نوشتن کد و بازبینی pull request قابل دسترس باشد.
چه چیزی را استاندارد کنیم؟
| حوزه | نمونه قاعده | روش کنترل |
|---|---|---|
| قالب‌بندی | فاصله، طول خط، import | formatter خودکار |
| کیفیت پایه | متغیر بلااستفاده، خطای نادیده | linter و CI |
| ساختار | مرز package و dependency | تست معماری + review |
| نام‌گذاری | واژگان دامنه و API | راهنما + review |
| خطا و log | پیام، سطح، داده حساس | helper، lint و review |
| تست | سطح لازم و سناریوی مرزی | CI + معیار پذیرش |
| امنیت | راز، اعتبارسنجی، دسترسی | scanner + review تخصصی |
| migration | سازگاری و rollback | checklist و محیط آزمایشی |
قواعدی را انتخاب کنید که خطای واقعی یا هزینه نگه‌داری را کم می‌کنند. سلیقه شخصی بدون اثر قابل توضیح نباید زمان بازبینی را مصرف کند.
۱. از خطاهای تکرارشونده شروع کنید
ده pull request برگشتی، incident و bug اخیر را مرور کنید. اگر مشکل بارها تکرار شده، نامزد استاندارد است. کپی راهنمای یک شرکت دیگر بدون دیدن درد تیم، سندی بزرگ و کم‌استفاده می‌سازد.
۲. هر قاعده را کوتاه و قابل آزمون بنویسید
برای هر مورد این ساختار کافی است: «قاعده»، «دلیل»، «نمونه درست/غلط» و «استثنا». عبارت «کد تمیز بنویسید» هیچ تصمیمی را هدایت نمی‌کند.
۳. کنترل قطعی را خودکار کنید
بحث درباره فاصله و ترتیب import نباید وقت بازبین را بگیرد. ابزار محلی و CI باید نتیجه یکسان بدهند و فرمان اجرای آن در repository ثبت شود.
۴. قواعد مرتبط را کنار تسک بیاورید
همه استانداردها برای همه کارها لازم نیستند. تسک migration باید چک‌لیست rollback را ببیند؛ تغییر رابط کاربری معیار دسترسی‌پذیری را. Context Pack می‌تواند فقط قواعد مرتبط را بازیابی کند.
۵. استثنا را ثبت کنید
گاهی کتابخانه قدیمی یا رخداد اضطراری مانع رعایت کامل است. استثنا باید دلیل، مالک، دامنه و در صورت نیاز تاریخ بازبینی داشته باشد. خاموش‌کردن دائمی linter با یک comment بدون توضیح، بدهی پنهان می‌سازد.
۶. قواعد را نسخه‌دار و بازنشسته کنید
مالک استاندارد و زمان بازبینی مشخص باشد. قاعده منسوخ را حذف کنید؛ انباشته‌شدن توصیه‌های متناقض اعتماد تیم را از بین می‌برد.
چک‌لیست کوتاه پیش از بازبینی
- معیار پذیرش تسک پوشش داده شده است.
- تست رفتار عادی، مرزی و خطا متناسب با تغییر وجود دارد.
- داده حساس در log، fixture یا commit نیست.
- رابط عمومی یا schema بدون برنامه سازگاری نشکسته است.
- migration مسیر بازگشت یا rollout امن دارد.
- تغییر نامرتبط وارد pull request نشده است.
- مستند یا runbook مرتبط در صورت نیاز به‌روز شده است.
این فهرست باید با نوع repository تغییر کند. چک‌لیست ۴۰ موردی به کلیک تشریفاتی تبدیل می‌شود.
نقش ابزار مدیریت پروژه
استاندارد زمانی به تحویل کمک می‌کند که به زمینه کار وصل باشد. تسک می‌تواند نوع تغییر، ریسک و معیار پذیرش را نگه دارد؛ pull request و نتیجه CI به همان تسک متصل شوند و رد بازبینی دلیل قابل اقدام داشته باشد.
در WKFGo، ابزار get_coding_standards می‌تواند قواعد تیم را برای دستیار یا توسعه‌دهنده بازیابی کند و submit_for_review تغییر را وارد صف بازبینی نماید. این اتصال جای CI یا repository protection را نمی‌گیرد؛ زمینه مدیریتی و فنی را کنار هم نگه می‌دارد.
استاندارد کدنویسی و دستیار AI
دستیار باید نسخه قواعد، زبان و مسیر مرتبط را در Context Pack بگیرد. گفتن «طبق استانداردهای تیم بنویس» بدون ارائه منبع، مدل را وادار به حدس می‌کند. خروجی AI باید همان formatter، linter، تست و review انسانی کد دیگر را طی کند.
قواعد امنیتی و معماری را فقط در prompt ننویسید؛ تا جای ممکن با تست و policy اجرایی کنید. متن راهنما می‌تواند فراموش یا نادیده گرفته شود.
شاخص‌های اثر
- تعداد دور بازبینی تا تأیید؛
- زمان انتظار و زمان فعال review؛
- دلیل‌های پرتکرار رد pull request؛
- خطاهای formatter/lint در CI که باید محلی گرفته می‌شدند؛
- defect پس از انتشار مرتبط با نقض استاندارد؛
- درصد استثناهای بدون مالک یا تاریخ؛
- زمان onboarding تا اولین تغییر پذیرفته‌شده.
تعداد rule یا هشدار بیشتر نشانه کیفیت نیست. استاندارد موفق باید دوباره‌کاری و اختلاف سلیقه را کم کند.
اشتباهات رایج
- ترکیب style، معماری و امنیت در یک سند طولانی؛
- قانون بدون دلیل و مثال؛
- کنترل دستی موضوعی که formatter حل می‌کند؛
- تغییر استاندارد بدون به‌روزرسانی CI؛
- استثنای دائمی و بی‌مالک؛
- استفاده از استاندارد برای سرزنش فرد؛
- الزام یکسان برای prototype و سرویس حساس بدون مدل ریسک.
استاندارد باید در ویکی باشد یا repository؟
قواعد نزدیک به کد و فرمان ابزار در repository نسخه‌گذاری شوند؛ سیاست‌های مشترک سازمان می‌توانند در ویکی باشند. بین آن‌ها لینک روشن و مالک واحد لازم است.
آیا پوشش تست درصد ثابتی داشته باشد؟
عدد ثابت به‌تنهایی کیفیت را تضمین نمی‌کند. مسیرهای بحرانی و تغییرکرده باید تست معنادار داشته باشند؛ درصد می‌تواند guardrail باشد، نه هدف نهایی.
چه کسی استاندارد را تغییر دهد؟
مالک فنی با بازخورد تیم. تغییر پراثر بهتر است به‌صورت proposal کوتاه، آزمایش و سپس اجرای خودکار انجام شود.
قدم بعدی
پنج دلیل پرتکرار رد pull request را استخراج کنید، فقط دو مورد قطعی را خودکار سازید و برای سه مورد قضاوتی مثال روشن بنویسید. برای رساندن قواعد مرتبط به دستیار AI، راهنمای Context Pack را ببینید.
منابع دست‌اول و روش راستی‌آزمایی
این فهرست برای بررسی بیشتر است؛ لینک‌های داخل متن، منبع ادعای مشخص همان بخش‌اند.