کافه استراحت شماره 20. کد قدیمی چیست و چگونه با آن کار کنیم. ابزارهایی که نوشتن اسناد فنی را آسان تر می کند

کد قدیمی چیست و چگونه با آن کار کنیم

منبع: Dou دیر و زود، یک برنامه نویس احتمالاً باید با کدهای قدیمی مواجه شود. برای کاهش عواقب این آشنایی، چند نکته و مثال عملی را از تجربه خودم انتخاب کرده ام - به ویژه کار با یک سیستم جاوا قدیمی.

ویژگی های میراث

Legacy کد شخص دیگری است که اغلب آنقدر وحشتناک است که معمولاً نحوه کار با آن مشخص نیست. و اگر مجبور باشید با یک سیستم قدیمی کار کنید، علاوه بر کد قدیمی، با موارد زیر نیز مواجه خواهید شد:

• با تکنولوژی قدیمی؛
• معماری ناهمگون؛
• فقدان یا حتی فقدان کامل مستندات.

در واقع، کد قدیمی آنقدرها هم ترسناک نیست، و دلیل آن این است: اگر سیستم در تمام این ده سال عمر کرده و هنوز هم کار می کند، پس مقداری کاربرد دارد. شاید درآمد خوبی داشته باشد (برخلاف آخرین استارتاپ شما). علاوه بر این، اگر این کد بتواند برای این مدت طولانی در تولید زنده بماند، نسبتاً قابل اعتماد است. بنابراین، تغییرات در آن باید با احتیاط انجام شود. اول از همه، شما باید دو چیز را درک کنید:

1. ما نمی توانیم به سیستمی بی احترامی کنیم که میلیون ها نفر در روز به آن دسترسی دارند یا هزاران نفر به آن دسترسی دارند. مهم نیست که چقدر ضعیف نوشته شده بود، این کد منزجر کننده تا زمان تولید زنده ماند و 24/7 کار کرد.

2. از آنجایی که این سیستم پول واقعی به ارمغان می آورد، کار با آن با مسئولیت زیادی همراه است. این یک استارت آپ نیست، بلکه چیزی است که کاربران فردا با آن کار خواهند کرد. این نیز مستلزم هزینه بسیار بالای خطا است و نکته اینجا در ادعاهای مشتری نیست، بلکه در وضعیت واقعی امور است.

مهندسی معکوس

برای کار موفقیت آمیز با کدهای قدیمی، باید از تکنیک های مهندسی معکوس استفاده کنید. ابتدا باید کد را با دقت بخوانید تا دقیقاً نحوه عملکرد آن را درک کنید. این اجباری است، زیرا ما به احتمال زیاد سندی نخواهیم داشت. اگر رشته فکری نویسنده را درک نکنیم، تغییراتی با عواقب غیرقابل پیش بینی ایجاد خواهیم کرد. برای محافظت از خود در برابر این، باید به کد مجاور نیز بپردازید. و در عین حال نه تنها در عرض، بلکه در عمق نیز حرکت کنید. روش با خطا در کجا فراخوانی می شود؟ کدی که آن را فراخوانی می کند از کجا آمده است؟ در یک پروژه قدیمی، "سلسله مراتب فراخوانی" و "سلسله مراتب نوع" بیشتر از هر چیز دیگری استفاده می شود. شما باید زمان زیادی را با دیباگر بگذرانید: اولاً برای یافتن خطاها و ثانیاً درک نحوه عملکرد همه چیز. در مورد مستندات، بد نیست به باستان شناسی صنعتی متوسل شویم. این می تواند بسیار مفید باشد که اسناد قدیمی را در جایی پیدا کنید و با کسانی صحبت کنید که به یاد دارند کدی که به ارث برده اید چگونه نوشته شده است. با استفاده از این تکنیک ها، دیر یا زود شما کم و بیش متوجه کد خواهید شد. اما برای جلوگیری از هدر رفتن تلاش‌هایتان، باید فوراً نتایج تحقیقات خود را مستند کنید. برای انجام این کار، ترسیم نمودارهای بلوکی یا نمودارهای توالی را توصیه می کنم. مطمئناً تنبل خواهید شد، اما حتماً باید این کار را انجام دهید، در غیر این صورت در شش ماه بدون مستندات، مانند بار اول، این کد را بررسی خواهید کرد.

کد را دوباره ننویسید

مهمترین چیز در فرآیند توسعه این است که به موقع خود را شکست دهید و سعی نکنید کل کد را از ابتدا بازنویسی کنید. تخمین بزنید که این کار به چند سال انسانی نیاز دارد. بعید است که مشتری بخواهد پول زیادی را برای انجام مجدد کاری که قبلاً کار می کند خرج کند. این نه تنها در مورد سیستم به عنوان یک کل، بلکه برای هر بخشی از آن نیز صدق می کند. البته ممکن است یک هفته به شما فرصت دهند تا همه چیز را بفهمید و یک هفته دیگر برای رفع مشکل. اما بعید است دو ماه به شما فرصت دهند تا دوباره بخشی از سیستم را بنویسید. در عوض، عملکرد جدید را به همان سبک بقیه کدها پیاده سازی کنید. به عبارت دیگر، اگر کد قدیمی است، نباید وسوسه شوید که از فناوری های جدید زیبا استفاده کنید: خواندن چنین کدهایی بسیار دشوار خواهد بود. به عنوان مثال، ممکن است با وضعیتی روبرو شوید که ما داشتیم: بخشی از سیستم در Spring MVC و بخشی در سرورهای خالی نوشته شده است. و اگر در قسمتی که در servlets نوشته شده است ، چیز دیگری باید اضافه شود ، آن را به همان روش اضافه می کنیم - در servlets.

به منافع تجاری احترام بگذارید

باید به خاطر داشت که هر کار، اول از همه، با ارزش برای تجارت تعیین می شود. اگر نیاز به تغییرات خاصی را از نقطه نظر تجاری به مشتری ثابت نکنید، این تغییرات اتفاق نمی افتد. و برای متقاعد کردن مشتری باید سعی کنید در جای او بایستید و علایق او را درک کنید. به‌ویژه، اگر می‌خواهید فقط به این دلیل که کد خواندنی سخت است، اصلاح کنید، اجازه انجام آن را نخواهید داشت و باید با آن زندگی کنید. اگر واقعاً نمی توانید آن را تحمل کنید، می توانید کد را بی سر و صدا و کم کم سازماندهی مجدد کنید و کار را در بلیط های تجاری پخش کنید. یا مشتری را متقاعد کنید که مثلاً این کار باعث کاهش زمان لازم برای یافتن خطاها و در نتیجه کاهش هزینه ها می شود.

تست

واضح است که تست در هر پروژه ای ضروری است. اما هنگام کار با سیستم‌های قدیمی، باید توجه ویژه‌ای به تست شود، زیرا تأثیر تغییرات ایجاد شده همیشه قابل پیش‌بینی نیست. شما حداقل به اندازه توسعه دهندگان به آزمایشگر نیاز دارید، در غیر این صورت باید در اتوماسیون فوق العاده خوب باشید. در پروژه ما، آزمایش شامل مراحل زیر بود:

1. تأیید، زمانی که عملکرد پیاده سازی شده یک ویژگی در یک شاخه جداگانه بررسی می شود.
2. تثبیت، زمانی که یک شاخه آزاد بررسی می شود که در آن همه ویژگی ها با هم ادغام می شوند.
3. صدور گواهینامه، زمانی که همان مورد مجدداً روی کیس های آزمایشی کمی متفاوت در یک محیط صدور گواهینامه اجرا می شود که از نظر مشخصات سخت افزاری و پیکربندی تا حد امکان به تولید نزدیک است.

و تنها پس از گذراندن تمام این سه مرحله می‌توانیم انتشار دهیم. احتمالاً کسی فکر می کند که صدور گواهینامه یک مرحله اضافی است، زیرا همه چیز قبلاً در مرحله تثبیت روشن شده است، اما تجربه ما نشان می دهد که اینطور نیست: گاهی اوقات در طول یک آزمایش رگرسیون که برای دور دوم روی دستگاه دیگری اجرا می شود، چیزی به نوعی بیرون خواهد آمد

DevOps و انتشار را رسمی کنید

برای مثال، روش انتشار می تواند به شرح زیر باشد. وقتی توسعه کامل شد و دو یا سه مرحله آزمایشی کامل شد، ما یک ایمیل برای تیم DevOps 36 ساعت قبل از زمان عرضه مورد انتظار می نویسیم. پس از این، تیم devops را فرا می‌خوانیم و در مورد همه تغییرات در محیط‌ها بحث می‌کنیم (آنها را در مورد همه تغییرات در پایگاه داده و پیکربندی مطلع می‌کنیم). برای هر تغییر یک سند (یک بلیط در جیرا) داریم. سپس، در حین انتشار، همه کسانی که در این امر دخیل هستند دور هم جمع می شوند و همه می گویند که الان چه کاری انجام می دهند: "ما پایگاه داده را آپلود کردیم"، "ما فلان سرورها را مجددا راه اندازی کردیم"، "ما رفتیم تا تست های رگرسیون را در محیط تولید اجرا کنیم. ” اگر مشکلی پیش بیاید، روند بازگشت به انتشار راه اندازی می شود، دقیقاً در سند اصلی توضیح داده شده است - بدون چنین سندی ما قطعاً چیزی را فراموش می کنیم یا گیج می شویم.

کنترل کیفیت کد

و در نهایت بازبینی کد عملی است که بنا به دلایلی در همه پروژه ها استفاده نمی شود. اگر هر قطعه کد توسط بیش از یک نفر بررسی شود، عالی است. حتی در یک تیم بسیار قوی، همیشه برخی از باگ ها در طول فرآیند بررسی کد کشف می شوند و اگر چند نفر به آن نگاه کنند، تعداد باگ های شناسایی شده افزایش می یابد. علاوه بر این، گاهی اوقات داور سوم یا چهارم بدترین چیز را پیدا می کند.

ابزارهایی که نوشتن اسناد فنی را آسان تر می کند

منبع: Dzone اکثر برنامه نویسان دوست ندارند مستندات فنی بنویسند. جرالد واینبرگ، کارشناس روان‌شناسی، حتی مستندات را «روغن کرچک برنامه‌نویسی» نامید: توسعه‌دهندگان عاشق خواندن آن هستند، اما به سادگی از نوشتن آن متنفرند. فقدان راهنمایی یا نقشه راه خالی منجر به کمبود اطلاعات در مورد نحوه عملکرد بخش های مختلف نرم افزار می شود. این در نهایت تجربه را برای کاربران نهایی کد بدتر می کند، زیرا در صورت عدم وجود مستندات، آنها نمی توانند به دقت و مفید بودن محصول اعتماد کنند. برای اینکه برنامه نویسان عادت به نوشتن اسناد را آسان تر کنند، توصیه می کنم به چهار ابزار عالی که اکنون تقریباً برای همه در دسترس است توجه کنید.

صفحات GitHub

احتمالاً امروزه هیچ توسعه دهنده ای وجود ندارد که تجربه کار بر روی GitHub را نداشته باشد. همچنین یک مکان عالی برای برنامه نویسانی است که به جایی برای ذخیره اسناد نیاز دارند. بسیاری از افراد از یک Readme استاندارد در پایگاه کد خود استفاده می کنند تا راهنمای ساده ای را در اختیار کاربر قرار دهند، اما این تنها راه برای ایجاد اسناد در GitHub نیست. با صفحات GitHub ، شما چیزی بیش از میزبانی صفحات پروژه خود، از جمله مستندات و آموزش ها، دریافت می کنید. شما می توانید به طور مستقیم با تمام مخازن GitHub تعامل داشته باشید و به توسعه دهندگان این امکان را می دهید که اسناد را به همان روشی که کد خود را به روز می کنند، به روز کنند. علاوه بر این، می توانید از Jekyll در اینجا استفاده کنید - به شما کمک می کند نشانه گذاری خود را به متن ساده یا به صفحات وب کامل تبدیل کنید.

Docs را بخوانید

همانطور که از نام آن پیداست، Read the Docs بستری برای ذخیره و خواندن اسناد در اختیار توسعه دهندگان قرار می دهد. این سرویس بسیار شبیه صفحات GitHub عمل می کند: برنامه نویسان می توانند تغییراتی را در اسناد از سیستم های کنترل نسخه مورد علاقه خود، از جمله Git، Bazaar، Mercurial و غیره ایجاد کنند. نسخه سازی خودکار و ایجاد صفحه نیز پشتیبانی می شود. بهترین بخش Read Docs انعطاف پذیری آن است. از webhook ها پشتیبانی می کند تا بتوانید بسیاری از فرآیند ایجاد سند را خودکار کنید. این یک صرفه جویی در زمان برای کاری است که اکثر برنامه نویسان نمی خواهند هیچ کاری با آن انجام دهند. علاوه بر این، هر چیزی که بر روی پلتفرم میزبانی می‌شود در قالب‌های مختلف، از جمله PDF، HTML تک صفحه‌ای و حتی فرمت کتاب الکترونیکی در دسترس عموم است. این سرویس بخش قابل توجهی از کار معمول به روز نگه داشتن اسناد را بر عهده می گیرد.

تترا

تترا فقط یک پلتفرم برای ذخیره اسناد نرم افزار نیست، بلکه یک پایگاه دانش کامل است. به ویژه زمانی که یک پروژه شامل گروه بزرگی از کدنویسان است که روی قطعات مختلف نرم افزار کار می کنند، خوب کار می کند. از تترا می توان برای مستندسازی پاسخ به سوالات رایج استفاده کرد.

زنبورستان

چیزی که Apiary را برای توسعه دهندگان بسیار مفید می کند، این واقعیت است که کار بسیار خوبی برای کمک به اسناد API انجام می دهد. این پلتفرم به کاربران امکان می‌دهد اسناد خود را در Markdown بنویسند ، از جمله تماس‌های API ساختگی. Apiary همچنین به شما امکان می دهد عناصر API را آزمایش و نمونه سازی کنید. به عبارت دیگر، یک ابزار مستندسازی و پلت فرم تست در یک مکان است.