استراحة القهوة رقم 20. ما هو الكود القديم وكيفية العمل معه. الأدوات التي تجعل كتابة الوثائق الفنية أسهل

ما هو الكود القديم وكيفية العمل معه

المصدر: Dou عاجلاً أم آجلاً، من المحتمل أن يواجه المبرمج كودًا قديمًا. ولتخفيف عواقب هذا التعارف، اخترت بعض النصائح والأمثلة العملية من تجربتي الخاصة - على وجه الخصوص، العمل مع نظام جافا القديم.

الميزات القديمة

Legacy هو رمز شخص آخر، وهو غالبًا ما يكون فظيعًا لدرجة أنه ليس من الواضح بشكل عام كيفية التعامل معه. وإذا كان عليك العمل مع نظام قديم، فبالإضافة إلى الكود القديم، ستواجه أيضًا ما يلي:

• مع التكنولوجيا التي عفا عليها الزمن.
• بنية غير متجانسة
• نقص أو حتى الغياب التام للوثائق.

في الواقع، الكود القديم ليس مخيفًا، وإليكم السبب: إذا كان النظام قد عاش كل هذه السنوات العشر وما زال يعمل، فهذا يعني أن له بعض الفائدة. ربما تحقق أموالاً جيدة (على عكس آخر شركة ناشئة لديك). بالإضافة إلى ذلك، يعتبر هذا الرمز موثوقًا نسبيًا إذا كان قادرًا على البقاء في الإنتاج لفترة طويلة. ولذلك، يجب إجراء التغييرات عليه بحذر. بادئ ذي بدء، عليك أن تفهم شيئين:

1. لا يمكننا عدم احترام النظام الذي يجني الملايين أو يصل إليه آلاف الأشخاص يوميًا. بغض النظر عن مدى سوء كتابته، فقد نجح هذا الكود المثير للاشمئزاز في الإنتاج ويعمل على مدار الساعة طوال أيام الأسبوع.

2. وبما أن هذا النظام يجلب أموالاً حقيقية، فإن العمل معه يأتي بمسؤولية كبيرة. هذه ليست شركة ناشئة، ولكنها شيء سيعمل عليه المستخدمون غدًا. وهذا يعني أيضًا تكلفة عالية جدًا للخطأ، والنقطة هنا ليست في مطالبات العميل، ولكن في الوضع الحقيقي للأمور.

الهندسة العكسية

للعمل بنجاح مع التعليمات البرمجية القديمة، سيتعين عليك استخدام تقنيات الهندسة العكسية. أولاً، تحتاج إلى قراءة التعليمات البرمجية بعناية لفهم كيفية عملها بالضبط. وهذا أمر إلزامي، لأننا على الأرجح لن يكون لدينا وثائق. إذا لم نفهم سلسلة أفكار المؤلف، فسوف نقوم بإجراء تغييرات ذات عواقب غير متوقعة. لحماية نفسك من هذا، تحتاج أيضًا إلى الخوض في الكود المجاور. وفي الوقت نفسه، لا تتحرك فقط في العرض، ولكن أيضا في العمق. أين يتم استدعاء الطريقة مع الخطأ؟ ومن أين يأتي الكود الذي يستدعيه؟ في المشروع القديم، يتم استخدام "التسلسل الهرمي للمكالمات" و"التسلسل الهرمي للأنواع" أكثر من أي شيء آخر. سيتعين عليك قضاء الكثير من الوقت مع مصحح الأخطاء: أولاً، للعثور على الأخطاء، وثانيًا، لفهم كيفية عمل كل شيء. أما بالنسبة للتوثيق، فلن يكون اللجوء إلى علم الآثار الصناعية فكرة سيئة. قد يكون من المفيد جدًا البحث عن الوثائق القديمة في مكان ما والتحدث مع أولئك الذين يتذكرون كيفية كتابة الكود الذي ورثته. باستخدام هذه التقنيات، ستبدأ عاجلاً أم آجلاً في فهم الكود بشكل أو بآخر. ولكن لكي لا تذهب جهودك هباءً، يجب عليك توثيق نتائج بحثك على الفور. للقيام بذلك، أوصي برسم المخططات الكتلية أو المخططات التسلسلية. بالطبع، سوف تكون كسولًا، لكنك بالتأكيد بحاجة إلى القيام بذلك، وإلا خلال ستة أشهر بدون توثيق، سوف تقوم بالتنقيب في هذا الرمز كما لو كانت المرة الأولى.

لا تعيد كتابة الكود

أهم شيء في عملية التطوير هو التغلب على نفسك في الوقت المحدد وعدم محاولة إعادة كتابة الكود بالكامل من الصفر. قم بتقدير عدد سنوات العمل التي سيتطلبها ذلك. من غير المحتمل أن يرغب العميل في إنفاق الكثير من المال على إعادة عمل شيء يعمل بالفعل. وهذا لا ينطبق فقط على النظام ككل، ولكن أيضًا على أي جزء منه. بالطبع، قد يعطونك أسبوعًا لمعرفة كل شيء، وأسبوعًا آخر لإصلاح شيء ما. لكن من غير المرجح أن يمنحك شهرين لكتابة جزء من النظام مرة أخرى. بدلاً من ذلك، قم بتنفيذ الوظيفة الجديدة بنفس نمط بقية التعليمات البرمجية. بمعنى آخر، إذا كان الكود قديمًا، فلا يجب أن تميل إلى استخدام تقنيات جميلة جديدة: سيكون من الصعب جدًا قراءة مثل هذا الكود. على سبيل المثال، قد تواجه موقفًا مثل ما واجهناه: جزء من النظام مكتوب في Spring MVC، وجزء مكتوب في servlets العارية. وإذا كان هناك حاجة إلى إضافة شيء آخر إلى جزء مكتوب في servlets، فإننا نضيفه بنفس الطريقة - في servlets.

احترام المصالح التجارية

يجب أن نتذكر أن أي مهام يتم تحديدها أولاً وقبل كل شيء حسب القيمة بالنسبة للعمل. إذا لم تثبت للعميل الحاجة إلى تغييرات معينة من وجهة نظر العمل، فلن تحدث هذه التغييرات. وحتى تقنع العميل عليك أن تحاول الوقوف مكانه وتفهم اهتماماته. على وجه الخصوص، إذا كنت تريد إعادة البناء لمجرد صعوبة قراءة الكود، فلن يُسمح لك بذلك، وسيتعين عليك التعايش معه. إذا كنت لا تستطيع تحمل ذلك حقًا، فيمكنك إعادة تنظيم الكود بهدوء وشيئًا فشيئًا، ونشر العمل عبر تذاكر العمل. أو إقناع العميل بأن هذا، على سبيل المثال، سوف يقلل من الوقت اللازم للعثور على الأخطاء، وبالتالي يقلل التكاليف في النهاية.

امتحان

من الواضح أن الاختبار ضروري في أي مشروع. ولكن عند العمل مع الأنظمة القديمة، يجب إيلاء اهتمام خاص للاختبار أيضًا لأن تأثير التغييرات التي يتم إجراؤها لا يمكن التنبؤ به دائمًا. ستحتاج إلى عدد من المختبرين على الأقل مثل عدد المطورين، وإلا فيجب أن تكون جيدًا بشكل لا يصدق في الأتمتة. في مشروعنا، يتكون الاختبار من المراحل التالية:

1. التحقق، عندما يتم فحص الوظيفة المنفذة لميزة ما في فرع منفصل.
2. التثبيت، عندما يتم التحقق من فرع الإصدار الذي يتم فيه دمج جميع الميزات معًا.
3. الشهادة، عندما يتم تشغيل نفس الشيء مرة أخرى في حالات اختبار مختلفة قليلاً في بيئة اعتماد تكون أقرب ما يمكن إلى الإنتاج من حيث خصائص الأجهزة وتكوينها.

وفقط بعد المرور بكل هذه المراحل الثلاث يمكننا إطلاق سراحنا. ربما يعتقد شخص ما أن الشهادة هي مرحلة إضافية، حيث تم بالفعل توضيح كل شيء في مرحلة الاستقرار، لكن تجربتنا تشير إلى أن الأمر ليس كذلك: في بعض الأحيان أثناء اختبار الانحدار، الذي يتم تشغيله للجولة الثانية على جهاز آخر، شيء ما بطريقة أو بأخرى سوف يخرج.

إضفاء الطابع الرسمي على DevOps والإصدار

يمكن أن تكون إجراءات الإصدار، على سبيل المثال، على النحو التالي. عند اكتمال التطوير واستكمال مرحلتين أو ثلاث مراحل اختبار، نكتب بريدًا إلكترونيًا إلى فريق DevOps قبل 36 ساعة من وقت الإصدار المتوقع. بعد ذلك، نتصل بفريق المطورين ونناقش جميع التغييرات في البيئات (نبلغهم بجميع التغييرات في قاعدة البيانات والتكوين). لكل تغيير لدينا وثيقة (تذكرة في جيرا). بعد ذلك، أثناء الإصدار، يجتمع جميع المشاركين في هذا معًا، ويقول الجميع ما يفعلونه الآن: "لقد قمنا بتحميل قاعدة البيانات"، "لقد أعدنا تشغيل خوادم كذا وكذا"، "لقد ذهبنا لإجراء اختبارات الانحدار في بيئة الإنتاج. " إذا حدث خطأ ما، فسيتم إطلاق إجراء التراجع عن الإصدار، الموصوف بدقة في مستند الإصدار الأصلي - بدون مثل هذا المستند، سننسى بالتأكيد شيئًا ما أو نشعر بالارتباك.

التحكم في جودة الكود

وأخيرًا، تعد مراجعة التعليمات البرمجية ممارسة لا يتم استخدامها لسبب ما في جميع المشاريع. من الرائع أن تتم مراجعة كل جزء من التعليمات البرمجية بواسطة أكثر من شخص واحد. حتى في فريق قوي جدًا، يتم اكتشاف بعض الأخطاء دائمًا أثناء عملية مراجعة التعليمات البرمجية، وإذا نظر إليها العديد من الأشخاص، يزداد عدد الأخطاء التي تم تحديدها. علاوة على ذلك، في بعض الأحيان يجد المراجع الثالث أو الرابع أسوأ شيء.

الأدوات التي تجعل كتابة الوثائق الفنية أسهل

المصدر: Dzone لا يحب معظم المبرمجين كتابة الوثائق الفنية. حتى أن خبير علم النفس جيرالد واينبرج وصف التوثيق بأنه "زيت الخروع للبرمجة": يحب المطورون قراءته، لكنهم ببساطة يكرهون كتابته بأنفسهم. يؤدي الافتقار إلى التوجيه أو خريطة الطريق الفارغة إلى نقص المعلومات حول كيفية عمل الأجزاء المختلفة من البرنامج. يؤدي هذا في النهاية إلى تفاقم تجربة المستخدمين النهائيين للكود، لأنه في غياب الوثائق، لا يمكنهم الاعتماد على دقة المنتج وفائدته. لتسهيل تكوين عادة كتابة الوثائق على المبرمجين، أوصي بالاهتمام بأربع أدوات ممتازة متاحة الآن للجميع تقريبًا.

صفحات جيثب

ربما لا يوجد مطور واحد اليوم ليس لديه خبرة في العمل على GitHub. إنه أيضًا مكان رائع للمبرمجين الذين يحتاجون إلى مكان لتخزين الوثائق. يستخدم العديد من الأشخاص الملف التمهيدي القياسي في قاعدة التعليمات البرمجية الخاصة بهم لتزويد المستخدم بدليل إرشادي بسيط، ولكن هذه ليست الطريقة الوحيدة لإنشاء الوثائق على GitHub. باستخدام صفحات GitHub ، يمكنك الحصول على أكثر من مجرد استضافة صفحات مشروعك، بما في ذلك الوثائق والبرامج التعليمية. يمكنك الحصول على القدرة على التفاعل مباشرة مع جميع مستودعات GitHub، مما يسمح للمطورين بتحديث الوثائق بنفس الطريقة التي يقومون بها بتحديث التعليمات البرمجية الخاصة بهم. علاوة على ذلك، يمكنك استخدام Jekyll هنا - فهو يساعدك على تحويل العلامات الخاصة بك إلى نص عادي أو إلى صفحات ويب كاملة.

اقرأ المستندات

كما يوحي الاسم، يوفر تطبيق Read the Docs للمطورين نظامًا أساسيًا لتخزين الوثائق وقراءتها. تعمل الخدمة كثيرًا مثل صفحات GitHub: يمكن للمبرمجين إجراء تغييرات على الوثائق من أنظمة التحكم في الإصدارات المفضلة لديهم، بما في ذلك Git وBazaar وMercurial وغيرها. يتم أيضًا دعم الإصدار التلقائي وإنشاء الصفحة. أفضل ما في تطبيق Read Docs هو مرونته. وهو يدعم خطافات الويب حتى تتمكن من أتمتة جزء كبير من عملية إنشاء المستندات. يعد هذا توفيرًا كبيرًا للوقت في مهمة لا يرغب معظم المبرمجين في القيام بها. بالإضافة إلى ذلك، كل شيء مستضاف على المنصة متاح لعامة الناس بتنسيقات متنوعة، بما في ذلك PDF وHTML صفحة واحدة وحتى تنسيق الكتاب الإلكتروني. تتولى الخدمة جزءًا كبيرًا من العمل الروتيني المتمثل في تحديث الوثائق.

تترا

Tettra ليست مجرد منصة لتخزين وثائق البرامج، ولكنها قاعدة معرفية كاملة. إنه يعمل بشكل جيد بشكل خاص عندما يتضمن المشروع مجموعة كبيرة من المبرمجين الذين يعملون على أجزاء مختلفة من البرامج. يمكن استخدام Tettra لتوثيق الإجابات على الأسئلة الشائعة.

المنحل

ما يجعل Apiary مفيدًا جدًا للمطورين هو حقيقة أنه يقوم بعمل رائع في المساعدة في توثيق API. يسمح النظام الأساسي للمستخدمين بكتابة وثائقهم في Markdown ، بما في ذلك مكالمات API الوهمية. يتيح لك Apiary أيضًا اختبار عناصر واجهة برمجة التطبيقات وإنشاء نماذج أولية لها. بمعنى آخر، إنها أداة توثيق ومنصة اختبار في مكان واحد.