هو PHPDoc الإسهاب أكثر صعوبة مما يستحق؟ [مغلق]

Question

وحاولت استخدام PHPDoc للمرة الأولى اليوم، وسرعان ما واجهت مشكلة.

لكل 1 خط من تعريفات المتغير، كان لا يقل عن 5 خطوط من التعليقات. مثال:

/**
 * Holds path the remote server
 * @name ...
 * @global ...
 */
 $myvar = ...

وبطبيعة الحال، فإن المكافآت هي لطيفة - ولكن هذا يتحول ملف التكوين 10 خط في ملف 60 خط. يأخذ مني إلى الأبد لملء، وأنا لم مقتنع أنه يضيف أن كثيرا على مر بسيطة أونيلينير.

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

وعلى رأس كل ذلك - أنه يدفعني إلى النمط C / ** / تعليقات في منتصف قانون بلدي. هذا يدفعني للجنون أثناء التطور لأنه يجرد القدرة على التعليق الخروج كتل كبيرة على الطلب. الآن أن أعلق خارج كتلة كبيرة من التعليمات البرمجية، ولست بحاجة لسحب شيء من هذا القبيل: النطاق، ق / ^ / # /. ثم التراجع عنه في وقت لاحق. مزعج!

وقصة قصيرة طويلة - أنا أحب PHPDoc، وأنا أحب موثقة جيدا كود - ولكن 5 خطوط من التعليقات لكل سطر واحد من التعليمات البرمجية <م> الكثير جدا !. هل هناك ميزات أنا في عداد المفقودين؟ هل هذه مشكلة شائعة؟

Answer 1

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

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

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

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