مشكلات طراحي API مرتبط با iTextSharp

كتابخانه‌ي iTextSharp،‌ يا همان برگردان iText جاوا،‌ انصافا اينقدر حرف براي گفتن دارد كه يك كتاب 600 صفحه‌اي براي آن چاپ شده است، اما ... در حين استفاده از آن مشكل زير (كه به شكل وسيعي در قسمت‌هاي مختلف آن وجود دارد) قابل هضم نيست:
يكي از مواردي را كه در حين طراحي يك API خوب بايد در نظر گرفت، كمك به استفاده كننده در عدم بكارگيري Magic numbers است. حالا اين Magic numbers يعني چي؟
براي مثال قطعه كد زير را در نظر بگيريد:

new Font(baseFont, 10, 0, BaseColor.BLACK)

مقدار پارامتر 3 در اينجا بي‌معنا است، مگر اينكه به مستندات مربوطه مراجعه كنيم.
نگارش بهبود يافته كد فوق به شرح زير است:

new Font(baseFont, 10, Font.NORMAL, BaseColor.BLACK)

كمي بهتر شد، اينبار ثوابت به يك كلاس منتقل شده‌اند و به اين ترتيب معناي مقدار بكارگرفته شده بدون نياز به مستندات متد فوق قابل درك است. اما اين روش هم (يعني همان روش متداول iTextSharp) دو مشكل مهم دارد:

• استفاده كننده محدوديتي در بكارگيري مقادير ندارد، چون آرگومان‌ها از نوع int معرفي شده‌اند. ممكن است اشتباهي رخ دهد.
• باز هم نياز است به مستندات كتابخانه مراجعه كرد، زيرا نوع int هيچ نوع منوي intellisense خاصي را ظاهر نمي‌كند.

راه درست، استفاده از enum است بجاي يك كلاس ساده كه فقط يك سري از ثوابت در آن تعريف شده‌اند. نوع int را بايد با enum زير جايگزين كرد (يا ... بهتر است اينگونه بشود در كتابخانه‌ي اصلي ... روزي!)

public enum PdfFontStyle
{
       Normal = 0,
       Bold = 1,
       Italic = 2,
       Underline = 4,
       Strikethru = 8,
       BoldItalic = Bold | Italic
}

اگر در طراحي آن از ابتدا اين روش پي‌گرفته مي‌شد، منوي intellisense تبديل به بهترين مستند اين كتابخانه مي‌شد.