كيف يمكنك تعريف جيدة أو سيئة API ؟ [مغلقة]

Question

الخلفية:

أنا مع فئة في جامعة تسمى "برامج القيود".في أول المحاضرات يمكننا تعلم كيفية بناء جيد واجهات برمجة التطبيقات.

وخير مثال لدينا من سيئة حقا API وظيفة المقبس public static void Select(IList checkRead, IList checkWrite, IList checkError, int microseconds); في C#.وظيفة يتلقى 3 قوائم من مآخذ ، ويدمر لهم مما يجعل المستخدم إلى استنساخ جميع مآخذ قبل التغذية عليها في Select().كما أن لديها مهلة (في ميكروثانية) الذي هو الباحث أن يحدد الحد الأقصى الوقت الخادم يمكن أن تنتظر مأخذ.حدود هذا هو +/-35 دقيقة (لأنه هو الباحث).

---

الأسئلة:

1. كيف يمكنك تحديد API كما 'سيئة'?
2. كيف يمكنك تعريف API بأنه 'جيد' ؟

---

النقاط في الاعتبار:

• وظيفة الأسماء التي من الصعب أن نتذكر.
• وظيفة المعلمات التي يصعب فهمها.
• سيئة الوثائق.
• كل شيء يجري مترابطة بحيث إذا كنت بحاجة إلى تغيير 1 سطر من التعليمات البرمجية سوف تحتاج في الواقع إلى تغيير مئات من الخطوط في أماكن أخرى.
• الوظائف التي تدمر حججهم.
• سيئة قابلية بسبب "خفية" التعقيد.
• هذا هو المطلوب من المستخدم/dev لبناء مغلفة حول API بحيث يمكن استخدامها.

Answer 1

في تصميم API لطالما وجدت هذه الرئيسي مفيدة جدا:
كيفية تصميم جيد API و لماذا يهم - من قبل يشوع بلوخ

وهنا مقتطفات, أنصح بقراءة كل شيء / مشاهدة الفيديو.

II.المبادئ العامة

• API يجب أن تفعل شيئا واحدا جيدا
  
• API يجب أن تكون صغيرة قدر الإمكان ولكن لا أصغر
  
• التنفيذ يجب أن لا تؤثر API
  
• تقليل إمكانية الوصول إلى كل شيء
  
• أسماء المسألة–API هو القليل من اللغة
  
• الوثائق المسائل
  
• الوثيقة دينيا
  
• النظر في الأداء عواقب API قرارات التصميم
  
• آثار API قرارات التصميم على الأداء الحقيقي و الدائم
  
• API يجب أن تتعايش سلميا مع منصة

III.فئة التصميم

• تقليل التحولية
  
• فئة فرعية فقط حيث أنه من المنطقي
  
• تصميم وثيقة الميراث أو آخر تحظر ذلك

IV.طريقة تصميم

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

Answer 2

لا يجب أن قراءة الوثائق لاستخدامها بشكل صحيح.

علامة رهيبة API.

Answer 3

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

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

أفضل المعلمين على الذوق هي التقليد (قراءة الكثير من التعليمات البرمجية APIs, معرفة ما يصلح وما لا يصلح) والخبرة (الوقوع في الخطأ والتعلم منه) والتفكير (لا تفعل فقط ما هو المألوف من أجل فكر قبل أن تعمل).

Answer 4

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

هناك المزيد ولكن هذا هو بداية جيدة

Answer 5

API جيد لديه النموذج الدلالي على مقربة من شيء فهو يصف.

على سبيل المثال, API لإنشاء و التلاعب في جداول البيانات إكسل قد فئات مثل Workbook, Sheet, ، Cell, مع أساليب مثل Cell.SetValue(text) و Workbook.listSheets().

Answer 6

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

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

Answer 7

لقد أحببت دائما هذه المادة في طابور بعنوان تصميم API المسائل

http://queue.acm.org/detail.cfm?id=1255422

و هذه الأعمدة أيضا أن يتعامل مع تصميم API مسائل:

http://queue.acm.org/detail.cfm?id=1229903

Answer 8

سيئة API هو واحد التي لم يتم استخدامها من قبل الجمهور المستهدف.

جيد API التي يتم استخدامها من قبل الجمهور المستهدف للغرض الذي تم تصميمه.

كبير API هو الذي يستخدم من قبل كل من المقصود الجمهور ، من أجل الغرض المقصود منه ، غير مقصود الجمهور لأسباب غير متوقعة من قبل المصممين.

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

كنت أتصور أن نفسه سوف يكون صحيحا بالنسبة لك.يمكنك أن تقرأ كل ما تريد عن تصميم و محاولة الخاص بك أفضل ، ولكن الاختبار سيتم استخدامها.قضاء بعض الوقت في بناء الطرق للحصول على ردود الفعل على ما يصلح وما لا يصلح وتكون على استعداد ريفاكتور حسب الحاجة لجعله أفضل.

Answer 9

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

Answer 10

هناك عدة إجابات جيدة على هذا بالفعل, حتى ظننت أنني كنت مجرد رمي في بعض الروابط لم أرى المذكورة.

المواد

1. "قليلا دليل تصميم API" من قبل ياسمين بلانشيت من ترولتيك
2. "تحديد QT الطراز C++ برمجة التطبيقات" أيضا ترولتيك

كتب:

1. "فعالية جافا" من قبل يشوع بلوخ
2. "ممارسة البرمجة" قبل كيرنيغان و رمح

Answer 11

أعتقد API جيد يجب أن تسمح مخصص IO و إدارة الذاكرة السنانير إذا كان المعمول بها.

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

هذا الرابط يحتوي على بعض النقاط الجيدة:http://gamearchitect.net/2008/09/19/good-middleware/

Answer 12

إذا API ينتج رسالة خطأ, تأكد من أن الرسالة التشخيص تساعد المطور معرفة ما هي المشكلة.

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

Answer 13

هو API سيئة عندما وثقت بشدة.

هو API جيدة عندما تم توثيقه جيدا و يتبع الترميز القياسية.

الآن هذه هي اثنين بسيطة جدا و أيضا من الصعب جدا يشير إلى اتباع هذا يجلب واحد في مجال هندسة البرمجيات.تحتاج مهندس جيد أن هياكل النظام ويساعد في إطار المتابعة الخاصة guidlines.

وتعليقا رمز كتابة وأوضح جيدا دليل API إلزامي.

API يمكن أن تكون جيدة إذا كان لديه وثائق جيدة وهو ما يفسر كيفية استخدامها.ولكن إذا كان رمز نظيفة و جيدة يلي القياسية داخل نفسها, لا يهم إذا كان doenst يكون لائق الوثائق.

لقد كتب القليل عن هيكل الترميز هنا

Answer 14

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