কেবল কোডটি দেখে কোনও এপিআই কী করছে তা সর্বদা জানতে হবে?

Question

সম্প্রতি আমি আমার নিজস্ব এপিআই বিকাশ করছি এবং এপিআই নকশায় বিনিয়োগের আগ্রহের সাথে আমি কীভাবে আমার এপিআই ডিজাইনটি উন্নত করতে পারি তা আগ্রহী।

একটি দিক যা কয়েকবার প্রকাশিত হয়েছে তা হ'ল (আমার এপিআই এর ব্যবহারকারীরা নয় তবে বিষয়টি নিয়ে আমার পর্যবেক্ষণ আলোচনায়): এপিআই কী করছে তা কল করে কোড দেখে কেবল একজনের জানা উচিত ।

উদাহরণস্বরূপ রেপো জন্য গিটহাবের উপর এই আলোচনাটি দেখুন , এটি কিছুটা এমন যায়:

foo.update_pinned(true, true);

কেবল কোডটি দেখে (প্যারামিটারের নাম, ডকুমেন্টেশন ইত্যাদি না জেনে) কেউ অনুমান করতে পারে না এটি কী করবে - ২ য় যুক্তির অর্থ কী? প্রস্তাবিত উন্নতিতে এরকম কিছু পাওয়া যায়:

foo.pin()
foo.unpin()
foo.pin_globally()

এবং এটি বিষয়গুলি পরিষ্কার করে দেয় (২ য় তর্কটি বিশ্বব্যাপী ফু পিন করা উচিত কিনা, আমি অনুমান করছি) এবং আমি এক্ষেত্রে সম্মতি জানাতে পরে অবশ্যই উন্নতি হবে।

তবে আমি বিশ্বাস করি যে এমন কিছু উদাহরণ থাকতে পারে যেখানে পৃথকভাবে কিন্তু যুক্তিযুক্তভাবে সম্পর্কিত রাষ্ট্র স্থাপনের পদ্ধতিগুলি পৃথকগুলির পরিবর্তে একটি পদ্ধতি কল হিসাবে আরও ভালভাবে প্রকাশিত হবে, যদিও আপনি কেবল কোডটি দেখেই জানেন না যে এটি কী করছে । (সুতরাং আপনাকে খুঁজে পেতে প্যারামিটারের নামগুলি এবং ডকুমেন্টেশনগুলি অবলম্বন করতে হবে - যা আমি কোনও এপিআই সম্পর্কে অপরিচিত হলে ব্যক্তিগতভাবে আমি সর্বদা যা কিছু করি না)।

উদাহরণস্বরূপ আমি ফ্যালকনপিয়ারেSetVisibility(bool, string, bool) একটি পদ্ধতি প্রকাশ করি এবং আমি স্বীকার করি যে কেবল লাইনটি দেখছে:

falconPeer.SetVisibility(true, "aerw3", true);

এটি কী করছে তা আপনার কোনও ধারণা নেই। এটি 3 টি পৃথক মান সেট করে falconPeerযা যৌক্তিক অর্থে "দৃশ্যমানতা" নিয়ন্ত্রণ করে : যোগদানের অনুরোধগুলি কেবল পাসওয়ার্ড সহ গ্রহণ করুন এবং আবিষ্কারের অনুরোধের জবাব দিন। এটিকে 3 পদ্ধতি কলগুলিতে বিভক্ত করা এআইপিআই-র একজন ব্যবহারকারীকে "দৃশ্যমানতা" এর একটি দিক নির্ধারণ করতে পারে যা অন্যদের সেট করতে ভুলে যায় যা আমি তাদের "দৃষ্টিগোচর" এর সমস্ত দিক সেট করার জন্য কেবল একটি পদ্ধতি প্রকাশ করেই তাকে ভাবতে বাধ্য করি । তদ্ব্যতীত যখন ব্যবহারকারী কোনও দিক পরিবর্তন করতে চান তারা প্রায়শই সর্বদা অন্য দিকটি পরিবর্তন করতে চান এবং এখন একটি কলে তা করতে পারেন।

Comments

কিছু ভাষায় প্যারামিটারের নামকরণ করা হয়েছে (কিছু সময় এমনকি নামযুক্ত প্যারামিটারগুলি প্রয়োগ করা হয়) এই কারণেই স্পষ্টভাবে । উদাহরণস্বরূপ, আপনি গ্রুপ একটি সহজ সেটিংস অনেকটা পারা updateপদ্ধতি: foo.update(pinned=true, globally=true)। বা: foo.update_pinned(true, globally=true)। সুতরাং, আপনার প্রশ্নের উত্তরটিও ভাষা বৈশিষ্ট্যগুলিকে বিবেচনায় নেওয়া উচিত, কারণ এক্স এক্স ভাষার জন্য একটি ভাল এপিআই ভাষা ওয়াই এবং বিপরীত ভাষার পক্ষে ভাল নাও হতে পারে।

— বাকুরিউ

সম্মত - বুলিয়ানগুলি ব্যবহার বন্ধ করুন :)

— ভেন

এটি "বুলিয়ান ট্র্যাপ"

— 11116 এ 11116 ব্যবহারকারীর 11153

@ বাকুরিউ ইভেন সি-তে এনাম রয়েছে, এমনকি যদি তারা ছদ্মবেশে পূর্ণসংখ্যা হয়। আমি মনে করি না এমন কোনও আসল বিশ্বের ভাষা আছে যেখানে বুলিয়ানগুলি ভাল এপিআই ডিজাইন।

— ডোভাল

আপনি কি বলার চেষ্টা করছেন তা আমি পেয়ে যাই না। আমি সেই পরিস্থিতিতে বুলিয়ান ব্যবহার করলাম কারণ ওপি সেগুলি ব্যবহার করেছিল তবে আমার বক্তব্যটি উত্তীর্ণ মানটির সাথে সম্পূর্ণ সম্পর্কিত নয়। উদাহরণস্বরূপ: setSize(10, 20)হিসাবে setSize(width=10, height=20)বা হিসাবে পাঠযোগ্য নয় random(distribution='gaussian', mean=0.5, deviation=1)। প্রয়োগ করা নামযুক্ত পরামিতিগুলির ভাষাগুলিতে বুলিয়ানগুলি enums / নামক ধ্রুবক ব্যবহারের মতো ঠিক একই পরিমাণের তথ্য জানাতে পারে, যাতে তারা API এ ভাল হতে পারে।

— বাকুরিউ

Answer 1

এটিকে তিনটি পদ্ধতির কলগুলিতে ভাগ না করার আপনার ইচ্ছাটি সম্পূর্ণরূপে বোধগম্য, তবে বুলিয়ান প্যারামিটারগুলির সাথে আপনার কাছে অন্যান্য বিকল্প রয়েছে।

আপনি এনাম ব্যবহার করতে পারেন:

falconPeer.SetVisibility(JoinRequestOptions.Accept, "aerw3", DiscoveryRequestOptions.Reply);

এমনকি একটি পতাকাও এনাম (যদি আপনার ভাষা এটি সমর্থন করে):

falconPeer.SetVisibility(VisibilityOptions.AcceptJoinRequests | VisibilityOptions.ReplyToDiscoveryRequests, "aerw3");

অথবা আপনি একটি প্যারামিটার অবজেক্ট ব্যবহার করতে পারেন :

var options = new VisibilityOptions();
options.AcceptJoinRequests = true;
options.ReplyToDiscoveryRequest = true;
options.Password="aerw3";
falconPeer.SetVisibility(options);

প্যারামিটার অবজেক্ট প্যাটার্নটি আপনাকে কয়েকটি অন্যান্য সুবিধা দেয় যা আপনি সহায়ক বলে মনে করতে পারেন। এটি ঘুরতে ও পরামিতিগুলির একটি সেট সিরিয়ালাইজ করা সহজ করে তোলে এবং আপনি সহজেই অনির্ধারিত পরামিতিগুলিকে "ডিফল্ট" মান দিতে পারেন।

অথবা আপনি কেবল বুলিয়ান প্যারামিটার ব্যবহার করতে পারেন। মাইক্রোসফ্ট এটি NET ফ্রেমওয়ার্ক এপিআই দিয়ে সারাক্ষণ কাজ করে বলে মনে হচ্ছে, যাতে আপনি কেবল এড়াতে এবং বলতে পারেন "এটি যদি তাদের পক্ষে যথেষ্ট ভাল হয় তবে এটি আমার পক্ষে যথেষ্ট ভাল"।

Comments

প্যারামিটার অবজেক্ট প্যাটার্নটিতে এখনও একটি সমস্যা রয়েছে ওপি বলেছে: " এটিকে 3 পদ্ধতি কলগুলিতে বিভক্ত করা এপিআই-র একজন ব্যবহারকারীকে" দৃশ্যমানতা "এর অন্য দিক সেট করতে ভুলে যেতে পারে" এর একটি দিক সেট করতে পারে ।

— লোড

সত্য, তবে আমি মনে করি এটি পরিস্থিতি আরও ভাল করে তোলে (নিখুঁত না হলে)। যদি ব্যবহারকারীকে ভিজিবিলিপশন অবজেক্টটি ইনস্ট্যান্ট করতে এবং পাস করতে বাধ্য করা হয়, তবে এটি (যে কোনও ভাগ্য সহ) তাদের মনে করিয়ে দিতে পারে যে ভিজিবিলিপশন অবজেক্টে অন্যান্য বৈশিষ্ট্য রয়েছে যা তারা সেট করতে চায়। তিনটি পদ্ধতির কলের পদ্ধতির সাথে, তাদের স্মরণ করিয়ে দেওয়ার জন্য যা কিছু পেয়েছে তা হ'ল তারা যে পদ্ধতিতে কল করছেন সে সম্পর্কে মন্তব্য।

— বেনম

Answer 2

স্পষ্টতই, নিয়মটিতে সর্বদা ব্যতিক্রম রয়েছে তবে আপনি নিজের দ্বারা ভালভাবে ব্যাখ্যা করেছেন, পঠনযোগ্য এপিআই থাকার কয়েকটি সুবিধা রয়েছে। বুলিয়ান আর্গুমেন্টগুলি বিশেষত বিরক্তিকর, যেমন 1) তারা কোনও অভিপ্রায় প্রকাশ করে না এবং 2) তারা বোঝায় যে আপনি কোনও ফাংশন বলছেন, যেখানে আপনার আসলে দুটি হওয়া উচিত, কারণ বুলিয়ান পতাকার উপর নির্ভর করে বিভিন্ন জিনিস ঘটতে চলেছে।

মূল প্রশ্নটি বরং: আপনি আপনার এপিআইকে আরও বেশি পঠনযোগ্য করে তুলতে কতটা বিনিয়োগ করতে চান? এটি যত বাহ্যিক-মুখোমুখি হয় তত বেশি প্রচেষ্টা সহজেই ন্যায়সঙ্গত হতে পারে। যদি এটি এমন একটি এপিআই হয় যা কেবলমাত্র অন্য একক দ্বারা ব্যবহৃত হয়, তবে এটি কোনও চুক্তির চেয়ে বড় নয়। আপনি যদি এমন একটি রেস্ট্রিং এপিআইয়ের কথা বলছেন যেখানে আপনি পুরো বিশ্বকে এটি হারাতে চান, তবে আপনি এটি আরও বোধগম্য করার জন্য আরও কিছু প্রচেষ্টা বিনিয়োগ করতে পারেন।

আপনার উদাহরণ হিসাবে, একটি সহজ সমাধান আছে: স্পষ্টতই, আপনার ক্ষেত্রে দৃশ্যমানতা কেবল একটি সত্য বা মিথ্যা জিনিস নয়। পরিবর্তে, আপনার কাছে এমন কিছু সামগ্রীর সেট রয়েছে যা আপনি "দৃশ্যমানতা" বিবেচনা করেন। একটি সমাধান হতে পারে একটি Visibilityশ্রেণীর মতো কিছু উপস্থাপন করা , যা এই সমস্ত ধরণের দৃশ্যমানতার অন্তর্ভুক্ত করে। আপনি যদি এগুলি তৈরির জন্য আরও পরে বিল্ডার-প্যাটার্ন প্রয়োগ করেন তবে আপনি নীচের মত কোড দিয়ে শেষ করতে পারেন:

Visibility visibility = Visibility.builder()
  .acceptJoinRequests()
  .withPassword("aerw3")
  .replyToDiscoveryRequests()
  .build();
falconPeer.setVisibility(visibility);