9.8 KiB
بازسازی کد و وظیفه مستندسازی
اهداف آموزشی
با تکمیل این تمرین، مهارتهای اساسی توسعه نرمافزار را که توسعهدهندگان حرفهای روزانه استفاده میکنند، تمرین خواهید کرد. یاد میگیرید چگونه کد را برای قابلیت نگهداری سازماندهی کنید، از طریق انتزاع تکرار کد را کاهش دهید و کار خود را برای توسعهدهندگان آینده (شامل خودتان!) مستند کنید.
کد تمیز و مستندسازی شده برای پروژههای واقعی توسعه وب که در آن چندین توسعهدهنده همکاری میکنند و کد در طول زمان تکامل مییابد، حیاتی است.
شرح وظیفه
فایل app.js مربوط به برنامه بانکی شما به طور قابل توجهی با عملکردهای ورود، ثبتنام و داشبورد رشد کرده است. اکنون زمان بازسازی این کد با استفاده از شیوههای توسعه حرفهای برای بهبود خوانایی، قابلیت نگهداری و کاهش تکرار رسیده است.
دستورالعملها
کد فعلی app.js خود را با اجرای این سه تکنیک اصلی بازسازی تغییر دهید:
۱. استخراج ثابتهای پیکربندی
وظیفه: یک بخش پیکربندی در بالای فایل خود ایجاد کنید که شامل ثابتهای قابل استفاده مجدد باشد.
راهنمای پیادهسازی:
- استخراج URL پایه API سرور (که در حال حاضر در چندین جا به صورت ثابت قرار دارد)
- ایجاد ثابتهایی برای پیامهای خطا که در چندین تابع تکرار میشوند
- در نظر داشته باشید مسیرهای مسیر و شناسههای عناصر که به صورت مکرر استفاده میشوند را استخراج کنید
ساختار نمونه:
// ثوابت پیکربندی
const API_BASE_URL = 'http://localhost:5000/api';
const ROUTES = {
LOGIN: '/login',
DASHBOARD: '/dashboard'
};
۲. ایجاد تابع درخواست یکپارچه
وظیفه: یک تابع sendRequest() قابل استفاده مجدد بسازید که کد تکراری بین createAccount() و getAccount() را حذف کند.
الزامات:
- پشتیبانی از درخواستهای GET و POST
- شامل رسیدگی مناسب به خطاها
- پشتیبانی از نقاط پایانی URL متفاوت
- پذیرش دادههای اختیاری در بدنه درخواست
راهنمای امضای تابع:
async function sendRequest(endpoint, method = 'GET', data = null) {
// پیادهسازی شما اینجا
}
۳. افزودن مستندسازی حرفهای کد
وظیفه: کد خود را با کامنتهای واضح و مفید مستندسازی کنید که «چرا» منطق شما را توضیح دهند.
استانداردهای مستندسازی:
- افزودن مستندسازی توابع که هدف، پارامترها و مقادیر بازگشتی را توضیح دهد
- گنجاندن کامنتهای درون خطی برای منطق پیچیده یا قوانین کسبوکار
- گروهبندی توابع مرتبط با سرصفحههای بخش
- توضیح هر الگو یا راهحل غیرواضح کد یا روشهای موقتی خاص مرورگر
نمونه سبک مستندسازی:
/**
* Authenticates user and redirects to dashboard
* @param {Event} event - Form submission event
* @returns {Promise<void>} - Resolves when login process completes
*/
async function login(event) {
// جلوگیری از ارسال پیشفرض فرم برای مدیریت با جاوااسکریپت
event.preventDefault();
// پیادهسازی شما...
}
معیارهای موفقیت
کد بازسازی شده شما باید این شیوههای توسعه حرفهای را نشان دهد:
پیادهسازی نمونه
- ✅ ثابتها: همه رشتههای جادویی (magic strings) و URLها به ثابتهایی با نامهای واضح استخراج شدهاند
- ✅ اصل DRY: منطق رایج درخواست در تابع
sendRequest()قابل استفاده مجدد تجمیع شده است - ✅ مستندسازی: توابع دارای کامنتهای JSDoc واضحی هستند که هدف و پارامترها را توضیح میدهد
- ✅ سازماندهی: کد به صورت منطقی با سرصفحههای بخش و قالببندی یکنواخت گروهبندی شده است
- ✅ مدیریت خطا: مدیریت خطا بهبود یافته با استفاده از تابع درخواست جدید
پیادهسازی کافی
- ✅ ثابتها: بیشتر مقادیر تکراری استخراج شدهاند، با مقادیر کمی که به صورت ثابت باقی ماندهاند
- ✅ فاکتورگیری: تابع
sendRequest()پایه ایجاد شده اما ممکن است همه حالتهای لبه را پوشش ندهد - ✅ کامنتها: توابع کلیدی مستندسازی شدهاند، اگرچه برخی توضیحات میتواند کاملتر باشد
- ✅ خوانایی: کد به طور کلی خوب سازماندهی شده است ولی هنوز جاهایی برای بهبود وجود دارد
نیازمند بهبود
- ❌ ثابتها: بسیاری از رشتههای جادویی و URLها در سراسر فایل به صورت ثابت باقی ماندهاند
- ❌ تکرار: تکرار قابل توجه کد بین توابع مشابه ادامه دارد
- ❌ مستندسازی: کامنتهای گمشده یا ناکافی که هدف کد را توضیح نمیدهند
- ❌ سازماندهی: کد ساختار و گروهبندی منطقی واضحی ندارد
تست کد بازسازی شده خود
پس از بازسازی، اطمینان حاصل کنید که برنامه بانکی شما هنوز به درستی کار میکند:
- آزمایش تمام مسیرهای کاربر: ثبتنام، ورود، نمایش داشبورد و مدیریت خطا
- تأیید تماسهای API: اطمینان از اینکه تابع
sendRequest()برای ایجاد و دریافت حساب کار میکند - بررسی سناریوهای خطا: آزمایش با اعتبارنامههای نامعتبر و خطاهای شبکه
- بازبینی خروجی کنسول: اطمینان از عدم وجود خطاهای جدید در حین بازسازی
دستورالعمل ارسال
فایل بازسازی شده app.js خود را با موارد زیر ارسال کنید:
- سرصفحههای بخش واضح که عملکردهای مختلف را سازماندهی میکند
- قالببندی و تورفتگی کد یکنواخت
- مستندسازی کامل JSDoc برای تمام توابع
- یک کامنت کوتاه در بالای فایل که رویکرد بازسازی شما را توضیح میدهد
چالش جایزه: یک فایل ساده مستندسازی کد (CODE_STRUCTURE.md) بسازید که معماری برنامه شما و نحوه کارکرد توابع مختلف را توضیح دهد.
ارتباط با دنیای واقعی
این تمرین بازتاب نوع نگهداری کدی است که توسعهدهندگان حرفهای به طور منظم انجام میدهند. در محیطهای صنعتی:
- مرور کد خوانایی و قابلیت نگهداری را مانند این تمرین ارزیابی میکند
- بدهی فنی زمانی انباشته میشود که کد مرتباً بازسازی و مستندسازی نشود
- همکاری تیمی به کد واضح و مستند شدهای تکیه دارد که اعضای جدید تیم بتوانند آن را درک کنند
- رفع باگها در کدهای سازمانیافته با انتزاعات مناسب بسیار سادهتر است
مهارتهایی که اکنون تمرین میکنید - استخراج ثابتها، حذف تکرار و نوشتن مستندسازی واضح - پایههای توسعه نرمافزار حرفهای هستند.
سلب مسئولیت:
این سند با استفاده از سرویس ترجمه هوش مصنوعی Co-op Translator ترجمه شده است. در حالی که ما برای دقت تلاش میکنیم، لطفاً توجه داشته باشید که ترجمههای خودکار ممکن است شامل خطاها یا نادرستیهایی باشند. سند اصلی به زبان بومی آن باید به عنوان منبع معتبر در نظر گرفته شود. برای اطلاعات حیاتی، ترجمه حرفهای انسانی توصیه میشود. ما در قبال هرگونه سوءتفاهم یا تفسیر نادرست ناشی از استفاده این ترجمه مسئولیتی نداریم.