وثائق API و"حدود القيمة":هل يتطابقان؟

Question

هل ترى غالبًا في وثائق API (كما هو الحال في "javadoc of public jobs" على سبيل المثال) وصف "حدود القيمة" بالإضافة إلى الوثائق الكلاسيكية؟

ملحوظة: أنا لا أتحدث عن التعليقات داخل الكود

أعني بـ "حدود القيمة" ما يلي:

• هل يمكن للمعلمة أن تدعم قيمة فارغة (أو سلسلة فارغة، أو...)؟
• هل يمكن أن تكون "قيمة الإرجاع" فارغة أو مضمونة ألا تكون فارغة أبدًا (أو يمكن أن تكون "فارغة" أو ...)؟

عينة:

ما أراه غالبًا (دون الوصول إلى كود المصدر) هو:

/**
 * Get all readers name for this current Report. <br />
 * <b>Warning</b>The Report must have been published first.
 * @param aReaderNameRegexp filter in order to return only reader matching the regexp
 * @return array of reader names
 */
 String[] getReaderNames(final String aReaderNameRegexp);

ما انا أود أن أرى سيكون:

/**
 * Get all readers name for this current Report. <br />
 * <b>Warning</b>The Report must have been published first.
 * @param aReaderNameRegexp filter in order to return only reader matching the regexp 
 * (can be null or empty)
 * @return array of reader names 
 * (null if Report has not yet been published, 
 *  empty array if no reader match criteria, 
 *  reader names array matching regexp, or all readers if regexp is null or empty)
 */
 String[] getReaderNames(final String aReaderNameRegexp);

ما أود أن أشير له هو:

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

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

يحرر:

هذا يمكن أن يؤثر على الاستخدام أم لا الاستثناءات المحددة أو غير المحددة.

ماذا تعتقد ؟هل حدود القيمة وواجهة برمجة التطبيقات (API) تنتميان معًا أم لا؟

Answer 1

اعتقد انهم يستطيع ينتمون معًا ولكن ليس بالضرورة يملك لننتمي معًا.في السيناريو الخاص بك، يبدو أنه من المنطقي أن يتم توثيق الحدود بطريقة تظهر في وثائق API التي تم إنشاؤها والتحسس الذكي (إذا كانت اللغة/IDE تدعم ذلك).

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

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

Answer 2

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

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

Answer 3

السؤال رقم 1

هل ترى غالبًا في وثائق API (كما هو الحال في "javadoc of public jobs" على سبيل المثال) وصف "حدود القيمة" بالإضافة إلى الوثائق الكلاسيكية؟

على الاغلب لا.

السؤال 2

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

إذا استخدمت وظيفة بشكل غير صحيح كنت أتوقع RuntimeException ألقيت بالطريقة أو أ RuntimeException في جزء آخر (أحيانًا بعيد جدًا) من البرنامج.

تعليقات مثل @param aReaderNameRegexp filter in order to ... (can be null or empty) يبدو لي وسيلة للتنفيذ التصميم حسب العقد بلغة الإنسان في الداخل جافادوك.

تم استخدام استخدام Javadoc لفرض التصميم حسب العقد بواسطة iContract, ، تم إحياءه الآن في JcontractS, ، التي تتيح لك تحديد الثوابت، الشروط المسبقة، الشروط اللاحقة, ، بطريقة أكثر رسمية مقارنة بلغة الإنسان.

السؤال 3

يمكن أن يؤثر هذا على الاستخدام أو لا يؤثر على الاستثناءات المحددة أو غير المحددة.ماذا تعتقد ؟هل حدود القيمة وواجهة برمجة التطبيقات (API) تنتميان معًا أم لا؟

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

Answer 4

أعتقد أنهم يفعلون ذلك، ودائمًا ما يضعون التعليقات في ملفات الرأس (c++) بشكل متتابع.

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

//File:
// Should be a path to the teexture file to load, if it is not a full path (eg "c:\example.png") it will attempt to find the file usign the paths provided by the DataSearchPath list
//Return: The pointer to a Texture instance is returned, in the event of an error, an exception is thrown. When you are finished with the texture you chould call the Free() method.
//Exceptions:
//except::FileNotFound
//except::InvalidFile
//except::InvalidParams
//except::CreationFailed
Texture *GetTexture(const std::string &File);

Answer 5

@فاير لانسر:يمين!لقد نسيت الاستثناءات، ولكني أود أن أراها مذكورة، وخاصة استثناء "وقت التشغيل" الذي لم يتم التحقق منه والذي يمكن أن تطرحه هذه الطريقة العامة

@ مايك ستون:

يجب عليك أيضًا أن تكون مجتهدًا لتحديث المستندات عند تغيير دلالات الطريقة.

مممم أنا بالتأكيد آمل أن وثائق API العامة يتم تحديثه على الأقل كلما حدث تغيير - يؤثر على عقد الوظيفة.إذا لم يكن الأمر كذلك، فقد يتم إسقاط وثائق واجهة برمجة التطبيقات هذه تمامًا.

لإضافة طعام إلى أفكارك (واذهب معScott Dorman)، لقد عثرت عليه للتو مستقبل التعليقات التوضيحية لـ Java7

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

بهذه الطريقة، إذا كان "@CheckForNull" موجودًا في واجهة برمجة التطبيقات، فقد يفلت كاتب الوظيفة من عدم توثيقه حتى!وإذا كان التغيير الدلالي، فإن واجهة برمجة التطبيقات (API) الخاصة به ستعكس هذا التغيير (مثل "لا مزيد من @CheckForNull" على سبيل المثال)

ويشير هذا النوع من النهج إلى أن التوثيق، بالنسبة لـ "الشروط الحدودية"، يمثل مكافأة إضافية وليس ممارسة إلزامية.

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