কোড কীভাবে ডকুমেন্ট করবেন?
আপনার ইতিমধ্যে একটি ইঙ্গিত রয়েছে: জাভা এপিআই কীভাবে ডকুমেন্ট করা আছে তা দেখুন।
আরও সাধারণভাবে, নিয়মের কোনও অনন্য সেট নেই যা প্রতিটি প্রকল্পের জন্য প্রযোজ্য। আমি যখন ব্যবসায়-সমালোচনামূলক বৃহত আকারের প্রকল্পগুলিতে কাজ করি, তখন একটি ছোট ওপেন সোর্স লাইব্রেরির জন্য আমি যা লিখব তার সাথে ডকুমেন্টেশনের কোনও সম্পর্ক নেই, যার ফলে আমার মাঝারি স্তরের ব্যক্তিগত প্রকল্পের ডকুমেন্টেশনের সাথে কোনও সম্পর্ক নেই has ।
কেন অনেক ওপেন সোর্স প্রকল্প ভাল ডকুমেন্টেড হয় না?
কারণ বেশিরভাগ ওপেন সোর্স প্রকল্পগুলি লোকেরা তৈরি করে যারা এই প্রকল্পগুলিতে অবদান রাখেন কারণ এটি মজাদার। বেশিরভাগ প্রোগ্রামার এবং ডেভেলপাররা বিবেচনা করে যে ডকুমেন্টেশন লেখার জন্য বিনামূল্যে করা যথেষ্ট মজাদার নয় ।
কেন অনেক বদ্ধ উত্স প্রকল্প ভাল নথিভুক্ত করা হয় না?
কারণ (1) ভাল ডকুমেন্টেশন লিখতে এবং (2) এটি বজায় রাখতে বিশাল অঙ্কের অর্থ ব্যয় হয়।
তাত্ক্ষণিক ব্যয় (ডকুমেন্টেশন লেখার ব্যয়) অংশীদারদের কাছে স্পষ্টভাবে দৃশ্যমান: আপনার দল যদি প্রকল্পটির ডকুমেন্টিংয়ের পরবর্তী দুই মাস ব্যয় করতে বলে, তবে এটি প্রদানের জন্য অতিরিক্ত দুই মাসের মাসের ব্যয়।
দীর্ঘমেয়াদী ব্যয় (ডকুমেন্টেশন বজায় রাখার ব্যয়) ম্যানেজারদের কাছে খুব সহজেই লক্ষণীয় হয়ে ওঠে এবং প্রায়শই প্রথম লক্ষ্য হয় যখন তাদের ব্যয়টি হ্রাস করতে হয় বা বিলম্বগুলি হ্রাস করতে হয়। এটি পুরানো ডকুমেন্টেশনের একটি অতিরিক্ত সমস্যা সৃষ্টি করে যা দ্রুত অকেজো হয়ে যায় এবং এটি আপডেট করা অত্যন্ত ব্যয়বহুল।
দীর্ঘমেয়াদী সঞ্চয় (বহু বছর আগে নথিভুক্ত করা উচিত এমন একটি মৌলিক জিনিসটি বোঝার জন্য উত্তরাধিকারের কোডটি অন্বেষণ করতে কিছু দিন নষ্ট না করা থেকে সঞ্চয়গুলি) অন্যদিকে, পরিমাপ করা কঠিন, যা কিছু পরিচালকের অনুভূতির সত্যতা নিশ্চিত করে ডকুমেন্টেশন রচনা এবং রক্ষণাবেক্ষণ করা সময়ের অপচয় waste
আমি প্রায়শই যা পর্যবেক্ষণ করি তা হ'ল:
শুরুতে, দলটি অনেকগুলি দলিল করতে রাজি।
সময়ের সাথে সাথে, সময়সীমা চাপ এবং আগ্রহের অভাব ডকুমেন্টেশন বজায় রাখা আরও এবং আরও কঠিন করে তোলে।
কয়েক মাস পরে, প্রকল্পের সাথে যুক্ত হওয়া একটি নতুন ব্যক্তি ডকুমেন্টেশন ব্যবহার করতে পারবেন না, কারণ এটি প্রকৃত সিস্টেমের সাথে মোটেই মিলছে না doesn't
লক্ষ্য করে যে, ব্যবস্থাপনা ডকুমেন্টেশন রক্ষণ না করার জন্য বিকাশকারীদের দোষ দেয়; বিকাশকারীরা এটি আপডেট করে কয়েক সপ্তাহ ব্যয় করতে বলেন।
পরিচালন যদি এর জন্য কয়েক সপ্তাহ মঞ্জুরি দেয় তবে চক্রটি পুনরাবৃত্তি করে।
যদি পূর্ববর্তী অভিজ্ঞতার ভিত্তিতে পরিচালনটি অস্বীকার করে তবে এটি কেবলমাত্র খারাপ অভিজ্ঞতা বাড়ায়, যেহেতু পণ্যের ডকুমেন্টেশন নেই, তবে কয়েক মাস ব্যয় করা হয়েছিল এটি রচনা ও বজায় রাখতে।
ডকুমেন্টেশন টেস্টের মতো একটি অবিচ্ছিন্ন প্রক্রিয়া হওয়া উচিত। কয়েক হাজার এলওসিকে কেবল কোডিংয়ে এক সপ্তাহ ব্যয় করুন এবং পরীক্ষা এবং ডকুমেন্টেশনগুলিতে ফিরে আসা খুব, খুব বেদনাদায়ক।
দলিল লেখার জন্য কীভাবে দলকে উত্সাহিত করবেন?
পরিষ্কারভাবে কোড লিখতে, নিয়মিত রিফ্যাক্টরিং করা, ডিজাইনের নিদর্শনগুলি ব্যবহার করতে বা পর্যাপ্ত ইউনিট পরীক্ষা যুক্ত করার জন্য মানুষকে উত্সাহিত করার উপায়গুলি একইভাবে।
উদাহরণ দ্বারা নেতৃত্ব. আপনি যদি ভাল ডকুমেন্টেশন লিখেন তবে আপনার জোড়গুলি এটি করাও শুরু করতে পারে।
ডকুমেন্টেশন পরিদর্শন লক্ষ্যবস্তু আনুষ্ঠানিক কোড পর্যালোচনা সহ পদ্ধতিগত কোড পর্যালোচনা করুন।
দলের কিছু সদস্য যদি বিশেষভাবে ভাল ডকুমেন্টেশন (বা ডকুমেন্টেশন) এর প্রতি অ্যান্টিপ্যাথিক হন তবে তাদের সাথে ব্যক্তিগতভাবে বিষয়টি নিয়ে আলোচনা করুন, আরও ভাল ডকুমেন্টেশন লেখার ক্ষেত্রে বাধা কী কী বাধা তা বোঝার জন্য। যদি তারা সময়ের অভাবকে দোষ দেয় তবে আপনি সমস্যার উত্স দেখতে পাচ্ছেন।
উপস্থিতি বা ডকুমেন্টেশনের অভাবকে কয়েক সপ্তাহ বা মাসের জন্য পরিমাপযোগ্য করে তুলুন তবে এতে মনোনিবেশ করবেন না। উদাহরণস্বরূপ, আপনি এলওসি অনুযায়ী মন্তব্যের লাইন সংখ্যা পরিমাপ করতে পারেন তবে এটিকে স্থায়ী পরিমাপ করবেন না, অন্যথায়, বিকাশকারীরা কেবল কম স্কোর থেকে মুক্তি পাওয়ার জন্য দীর্ঘ কিন্তু অর্থহীন মন্তব্যগুলি লিখতে শুরু করবেন।
গ্যামিফিকেশন ব্যবহার করুন। এটি পূর্ববর্তী পয়েন্টের সাথে একসাথে আসে।
ইতিবাচক / নেতিবাচক শক্তিবৃদ্ধি ব্যবহার করুন ।
( এসজুয়ান 76 এর মন্তব্য দেখুন ) মন্তব্যগুলির অভাবকে ত্রুটি হিসাবে বিবেচনা করুন। উদাহরণস্বরূপ, ভিজ্যুয়াল স্টুডিওতে, আপনি এক্সএমএল ডকুমেন্টেশন তৈরির জন্য একটি বিকল্প চেক করতে পারেন। আপনি যদি এটিও পরীক্ষা করে থাকেন যে সমস্ত সতর্কতাগুলি ত্রুটি হিসাবে বিবেচিত হয় তবে কোনও শ্রেণীর শীর্ষে বা কোনও পদ্ধতির মন্তবীর অভাব সংকলনটি থামিয়ে দেবে।
পূর্ববর্তী তিনটি বিষয় হিসাবে, এটি একটি সতর্কতার সাথে ব্যবহার করা উচিত। আমি এটি প্রাথমিকভাবে প্রোগ্রামারদের একটি বিশেষ শক্ত দলের সাথে কিছু সময়ের জন্য ব্যবহার করেছি এবং এটি স্টাইলকপ-অনুগত মন্তব্যগুলির সাথে শেষ হয়েছে:
/// <summary>
/// Gets or sets the PrimaryHandling.
/// </summary>
public Workflow PrimaryHandling { get; set; }
যেগুলি, এইচএম ..., বিশেষভাবে সহায়ক ছিল না।
মনে রাখবেন: প্রোগ্রামাররা যখন আপনার সাথে কথা বলতে চায় তখন স্বয়ংক্রিয় কিছুই আপনাকে খারাপ মন্তব্য চিহ্নিত করতে সহায়তা করতে পারে না । কেবল কোড পর্যালোচনা এবং অন্যান্য মানবিক কার্যগুলি সহায়তা করবে।
যখন ন্যূনতম বা কোনও ডকুমেন্টেশন প্রয়োজন হয় তার কোনও ভাল উদাহরণ রয়েছে?
আর্কিটেকচার এবং নকশা ব্যাখ্যা করে ডকুমেন্টেশন প্রয়োজন হয় না:
প্রোটোটাইপের জন্য,
কোনও কার্য সম্পাদনের জন্য কয়েক ঘন্টার মধ্যে লেখা একটি ব্যক্তিগত প্রকল্পের জন্য, যদিও এই প্রকল্পটি আর বজায় রাখা হবে না পুরোপুরি নিশ্চিত হয়ে,
যে কোনও প্রকল্পের জন্য এটি স্পষ্টরূপে, এর ছোট আকারকে দেওয়া, বিশেষত পরিষ্কার কোডের সাথে মিলিয়ে, আপনি কোডটি অন্বেষণে ভবিষ্যতের সমস্ত রক্ষণাবেক্ষণকারীদের চেয়ে ডকুমেন্টেশন লেখাতে বেশি সময় ব্যয় করবেন।
কোডটি স্ব-ডকুমেন্টিংয়ের সময় কিছু বিকাশকারীদের মতে কোড কোড ডকুমেন্টেশন (কোড মন্তব্য) প্রয়োজন হয় না। তাদের জন্য, মন্তব্যগুলির উপস্থিতি বিরল ক্ষেত্রে ব্যতীত, কোনও ভাল চিহ্ন নয়, তবে একটি চিহ্ন যে মন্তব্যটির প্রয়োজন ছাড়াই কোডটি যথেষ্ট পরিমাণে পরিষ্কার করা হয়নি act
আমি মনে করি যে কোনও প্রকল্প বিতরণের পরে আমাদের একটি ডকুমেন্টেশন রিভিউ থাকা উচিত।
যদি আপনার প্রকল্পটি প্রতি সপ্তাহে অন্তত একবার বিতরণ করা হয় তবে এটি যাওয়ার উপায়। যদি আপনার প্রকল্পটি তাত্পর্যপূর্ণ না হয় এবং ছয় মাসের ব্যবধানে সরবরাহ করা হয়, তবে আরও নিয়মিত পর্যালোচনা করুন।