কোড ডকুমেন্টেশনের উত্পাদনশীলতা লাভ / ক্ষতির বিষয়ে অধ্যয়ন


11

অনেক অনুসন্ধানের পরেও, আমি সফ্টওয়্যার বিকাশের বিশ্বে পরিচিত একটি অনুমান সম্পর্কিত সম্পর্কিত একটি প্রাথমিক প্রশ্নের উত্তর দিতে ব্যর্থ হয়েছি:

কী জানে:

পর্যাপ্ত কোড ডকুমেন্টেশন সম্পর্কে কঠোর নীতি প্রয়োগ (এটি ডক্সিজেন ট্যাগ, জাভাদোক বা কেবলমাত্র প্রচুর মন্তব্য) কোড বিকাশের জন্য প্রয়োজনীয় সময়কে ওভার-হেড যোগ করে।

কিন্তু:

পুঙ্খানুপুঙ্খ ডকুমেন্টেশন (বা এমনকি একটি এপিআই) থাকা নতুন এবং পাকা বিকাশকারীদের যখন বৈশিষ্ট্যগুলি যুক্ত করা হয় বা রাস্তার নিচে বাগগুলি স্থির করে থাকে তখন তাদের সাথে উত্পাদনশীলতা লাভ (এককভাবে ধরে নেওয়া হয়) নিয়ে আসে।

প্রশ্নটি:

ডাউন-দ্য রোড (কঠোরভাবে অর্থনৈতিক দিক দিয়ে) উত্পাদনশীলতার লাভের মাধ্যমে এই জাতীয় ডকুমেন্টেশন অফসেটের গ্যারান্টি দেওয়ার জন্য যুক্ত বর্ধিত সময়ের কি প্রয়োজনীয়?

আমি কেস স্টাডি, বা উত্তরগুলি সন্ধান করছি যা তাদের সাথে উত্থাপিত সিদ্ধান্তগুলি সমর্থন করার উদ্দেশ্যে উদ্দেশ্যমূলক প্রমাণ আনতে পারে।

আগাম ধন্যবাদ!


আপনি যদি মতামত খুঁজছেন, এটি প্রোগ্রামার.স এর উপর নির্ভর করে।
ডেভিড থর্নলি

আমি তা নিয়ে সরানো উচিত ছিল না। স্পষ্ট করার জন্য, আমি দৃONG়ভাবে যে পড়াশোনা করেছি তার সন্ধান করছি।
জেটি

সম্পাদনা করা হয়েছে। একজন মডারেটর দয়া করে এটি আবার স্ট্যাক ওভারফ্লোতে স্থানান্তরিত করতে পারেন যেখানে এই প্রশ্নটি এর ব্যাপক সম্ভাবনাগুলি আরও বেশি বিস্তৃত শ্রোতাদের উপভোগ করবে।
জেটি

8
আমি মনে করি না যে এটি এসডির পক্ষে উপযুক্ত প্রশ্ন কারণ এটি কোনও কোডিং প্রশ্ন নয়, কোডিং সম্পর্কিত একটি প্রশ্ন। আমি আসলেই মনে করি এটি প্রোগ্রামারদের জন্য একটি নিখুঁত প্রশ্ন।
ক্রিসএফ

উত্তর:


6

"প্রবন্ধের তুলনায় টাইপোগ্রাফিক শৈলী বেশি" প্রবন্ধটি পুরানো তবে এটি অত্যন্ত আকর্ষণীয়: http://portal.acm.org/citation.cfm?id=78611

পুরাতন হচ্ছে, এটা সব অভিনব কাপড় যে এই দিন সম্ভব হবে অন্তর্ভুক্ত নয় কিন্তু এটা স্পষ্টভাবে দেখায় যে কোড ডকুমেন্টেশন করে ব্যাপার।

আমার মতো যারা এসিএম ডিজিটাল লাইব্রেরিতে অ্যাক্সেস পান না, তারা দুটি গ্রুপ প্রোগ্রামার তৈরি করেছিলেন এবং তাদের একই কোডটি অধ্যয়নের জন্য দিয়েছিলেন। গ্রুপ এ সাধারণ মন্তব্যগুলির সাথে কেবল কোডটি পেয়েছিল, গ্রুপ বি একটি সুন্দর মুদ্রিত তালিকা পেয়েছে বিষয়বস্তুর সারণী, ক্রস রেফারেন্স এবং 1990 সালে ফিরে আসা সমস্ত চমত্কার জিনিস।

তারপরে তারা দুটি গ্রুপকে কোডে কিছু নির্দিষ্ট কার্য সম্পাদন করতে বলে (যেমন একটি ফাংশন প্রসারিত করুন, একটি বাগ সন্ধান করুন, ...) এবং উত্তরের গতি এবং গুণমানের মেয়াদে তাদের গোল করেছেন।

গোষ্ঠীর ভারসাম্য রক্ষার জন্য তাদের কাছে বিশেষজ্ঞ ও জুনিয়র প্রোগ্রামারগুলির একই সংখ্যা ছিল।

ঠিক আছে, এটি প্রমাণিত হয়েছে যে গ্রুপ বি (বেশিরভাগ প্রিন্টেড তালিকাভুক্ত একটি) ক্রিয়াকলাপে আরও ভাল রান করেছে তারপরে অসংখ্য গ্রুপে গ্রুপ এ। এবং, নির্দিষ্ট ক্ষেত্রে, গ্রুপ এ এর ​​মধ্যে সবচেয়ে বিশেষজ্ঞরা গ্রুপ বিয়ের জুনিয়র প্রোগ্রামারকে ছাড়িয়ে গেছে managed

নিবন্ধটি আরও বলেছে তবে এটিই আমি স্মৃতি থেকে প্রত্যাহার করতে পারি (আমার এখনও কোথাও মুদ্রিত নিবন্ধ থাকা উচিত)।


8

আমার পক্ষে কমপক্ষে, এটি স্পষ্ট বলে মনে হয় যে পাঠযোগ্য কোডটি ডকুমেন্টেশনের চেয়ে অনেক বেশি মূল্যবান যা কেবলমাত্র খারাপভাবে লিখিত কোড তৈরির জন্য কাজ করে। আমি কোডটিতে মন্তব্যগুলিকে কোডটি পুনরায় লেখার মাধ্যমে মুছে ফেলতে এবং এটিকে আরও স্ব-ব্যাখ্যা করে তুলতে পারি কিনা তা দেখার চ্যালেঞ্জ হিসাবে কোডে মন্তব্যগুলি বিবেচনা করার ঝোঁক।

সাধারণ জ্ঞান বাদে আমি কোনও শক্ত প্রমাণ দিয়ে এটিকে ব্যাক করতে পারি না।


পুরো পদ্ধতিটি পড়ার পরিবর্তে কোনও পদ্ধতি ব্যবহার করার জন্য কেবল কিছু জাভাদোকের মাধ্যমে পড়ার জন্য অর্থনৈতিক বোধ তৈরি হয়
হাইকো রুপ

2
@ হাইকো: ফাংশনটির নাম এবং প্যারামিটারের নামগুলি থেকে কোনও ফাংশন কী করে তা যদি আপনি অনুধাবন করতে না পারেন তবে তাদের নামকরণের সময় এসেছে।
সোজয়ের্ড

4
আমি এই উত্তরের সাথে একমত, তবে কখনও কখনও আপনার মতো বিষয়গুলির জন্য ডকুমেন্টেশন যুক্ত করতে হবে: বৈধ ফেরতের মানগুলি কী? বৈধ ইনপুট মানগুলি কী কী? এটি কীভাবে প্রোগ্রামের সামগ্রিক কাঠামোর সাথে খাপ খায়? পদ্ধতির প্রয়োজনীয়তাগুলি কী কী?
ডোমিনিক ম্যাকডোনেল

2
@ সোজার্ড: এটি আপনাকে পদ্ধতিটি কী করে তার একটি বিস্তৃত ওভারভিউ দিতে পারে, তবে এটি আপনাকে সব কিছু বলে না। মঞ্জুরিযোগ্য ইনপুট মানগুলি, এটি কী ফিরে আসতে পারে, কীভাবে এটি ত্রুটিগুলি পরিচালনা করে, কী পূর্ববর্তী অবস্থাটি প্রত্যাশা করে ইত্যাদি যথাযথ পদ্ধতি এবং প্যারামিটারের নামগুলি চয়ন করে এগুলি দেওয়া অসম্ভব।
আনন

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

6

আমার উদ্ধৃতি দেওয়ার জন্য কোনও অধ্যয়ন নেই, তবে আমার একটি সহজ নিয়ম রয়েছে: আমি যদি দুই সপ্তাহ পরে আমার কোডটিতে ফিরে আসি এবং আমি কী করেছি তা অবিলম্বে অনুধাবন করতে না পারি, তবে এটির আরও মন্তব্য প্রয়োজন, বা সরলকরণের প্রয়োজন ।

অবশ্যই, আপনার কোড কীভাবে কাজ করে তা কোড দ্বারা নথিভুক্ত করা উচিত। তবে সময় এমন মন্তব্য লেখার জন্য ব্যয় করেছে যা সাবধানতার সাথে এবং সংক্ষিপ্তভাবে ব্যাখ্যা করে যে আপনার কোডটি কেন এভাবে লেখা হয় এটি অবশ্যই দীর্ঘমেয়াদে নিজের জন্য প্রদান করে, এমনকি আপনি যদি এই কোডটি বজায় রাখেন এমন একমাত্র ব্যক্তি।

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


3

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

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


ব্যবহারের নিদর্শনগুলির জন্য +1। আমার সাথে কাজ করার মতো অন্য কিছু না থাকলে কোডের নমুনাগুলি যথেষ্ট would
রবার্ট হার্ভে

সর্বোত্তম পয়েন্টের জন্য +1 যে সম্ভবত কোডের উদাহরণগুলি একটি পরিষ্কার এপিআইর চেয়ে বেশি গুরুত্বপূর্ণ।
জেটি

@ জেটি: আমি অনুভূতিটি পছন্দ করি তবে আমি বরং তা পুনরায় প্রচার করতে চাই:Clean common usage scenarios are more important than a clean API
মার্টিন ইয়র্ক

1

প্রদত্ত পদ্ধতিটি এমন কোনও সরঞ্জাম ছাড়াই কিনা সিদ্ধান্ত, সম্ভবত এখনও আবিষ্কার করা হয়নি, সেই ডকুমেন্টেশনটি লেখার প্রয়োজন হয় না এমন বিষয়ভিত্তিক ।

যেকোন সেরা অনুমানের অনুশীলন যেমন "সমস্ত পাবলিক পদ্ধতি" বা প্রদত্ত প্যাকেজের সমস্ত শ্রেণি ইত্যাদি, সহায়তা করতে পারে তবে নির্দিষ্ট ব্যবহারের ক্ষেত্রে এর বাইরে সুপারিশ করা খুব রুক্ষ নয়।

আমার পরামর্শ: আপনার বিকাশকারীদের ভাল অনুশীলন শেখান, ডকুমেন্টের জন্য গুরুত্বপূর্ণ পদ্ধতিগুলি কীভাবে সনাক্ত করতে হয় (আনুষ্ঠানিক বা অনানুষ্ঠানিক এপিআই, সাধারণত ব্যবহৃত, স্টাব পদ্ধতি, জটিল বা রহস্যময়) এবং তাদের নিজেরাই পরিচালনা করতে দিন।

(ঘনিষ্ঠভাবে সম্পর্কিত: কোডিং স্ট্যান্ডার্ডে খুব বেশি অভিন্নতা থাকতে পারে? )


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


1

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

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

সম্ভাব্য ব্যতিক্রমগুলি হল পারফরম্যান্স অপটিমাইজড কোড, বা একটি নির্দিষ্ট অ্যালগরিদম ব্যবহার করে । এই ক্ষেত্রে কোডটি কেন দেখতে অ্যালগরিদমের একটি রেফারেন্স মনে হচ্ছে তা বর্ণনা করতে মন্তব্য যুক্ত করা দরকারী etc.

এই বিষয়টির উপরের কাজটি ক্লিন কোড

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


1

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


কোডটি ভার্বোজ এবং যথেষ্ট পরিষ্কার কিনা তা প্রয়োজন কিনা তা সনাক্ত করার জন্য কোড পর্যালোচনাটিকে ব্যবহার করার মত ধারণা হিসাবে +1। ক্লিন এপিআই পরীক্ষার্থীদের ইউনিট পরীক্ষাগুলি লিখতে কীভাবে সহায়তা করে সে সম্পর্কেও দুর্দান্ত বক্তব্য
জেটি

0

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

সুতরাং কোডটি খুব ভালভাবে মন্তব্য করা উচিত এবং তাই স্ব-ডকুমেন্টেড কোড হওয়া উচিত যা কোনও বাহ্যিক ডকুমেন্টেশন প্রয়োজন হয় না।


0

আমার কেরিয়ারে, আমি বিভিন্ন স্তরের ডকুমেন্টেশন এবং মানের সহ কোডটি দেখেছি (নোট করুন যে ডকুমেন্টেশন এবং মানটি অर्थোগ্যানাল উদ্বেগসমূহ)। আমি মান উন্নত করতে ডকুমেন্টেশন ব্যয় সময় পছন্দ করতে চাই। সাধারণ মামলার জন্য ঘোস্টডকের মতো সরঞ্জাম রয়েছে যা কোনও ফাংশন দেখে এবং আপনার জন্য ডক মন্তব্য তৈরি করতে পারে। যদি গোস্টডক কোনও অর্থবহ মন্তব্য তৈরি করতে পারে যা আপনার ফাংশনটি কী করে তা বলে, তবে আপনি অবশ্যই সুপরিচিত ফাংশনগুলি করার লক্ষ্য অর্জন করেছেন।

অনেক ক্ষেত্রে, ঘোস্টডক এমনকি কোনও ফাংশন আসলে কী তা আপনাকে বলতে শুরু করতে পারে না। আপনার সময়টি সেই ইস্যুটি সম্বোধন করার জন্য এবং (সম্ভবত) নিজের কোডটি স্বয়ংক্রিয়ভাবে জেনস্টেটের জন্য ব্যবহার করে spent

গভীর আলোচনার জন্য বব মার্টিনের কাছ থেকে ক্লিন কোড এবং পিপিপি দেখুন ।

আমাদের সাইট ব্যবহার করে, আপনি স্বীকার করেছেন যে আপনি আমাদের কুকি নীতি এবং গোপনীয়তা নীতিটি পড়েছেন এবং বুঝতে পেরেছেন ।
Licensed under cc by-sa 3.0 with attribution required.