আপনার সব কিছুর ডকুমেন্ট করা উচিত নাকি সর্বাধিক?

Question

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

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

সুতরাং আমি কখন ডকুমেন্ট করব? মাঝে মাঝে কোডের কোড থাকলেও কি আমি সবকিছু নথিভুক্ত করি? বা আমি আমার দৃষ্টিতে কিছুই প্রকাশ করি না কেন এটি "সুস্পষ্ট"?

Comments

একটি নির্দিষ্ট ডিগ্রীতে এটি একটি নামকরণের সমস্যা দেখায় যেমন গেটডেটটি getCreationDate বা getExpiryDate হওয়া উচিত বা ডোমেনে কখনই অর্থবোধ করা উচিত। অবশ্যই নামকরণ কোনও পঞ্চাশক্তি নয়।

— জে কে।

দ্রষ্টব্য: এটি সিভি পর্যালোচনার সারিতে উঠে এসেছে। আমি মনে করি এটি উন্মুক্ত রাখা উচিত - প্রশ্নটি অন টপিক (ডকুমেন্টেশন এসডিএলসি) এবং উত্তরগুলি সত্যই ভাল এবং যুক্তিসঙ্গত পরিমাণে প্রশ্নের উত্তর দিন (খুব বেশি বিস্তৃত নয়)

Answer 1

ডকুমেন্টে জ্ঞান করে এমন সমস্ত কিছু নথিভুক্ত করুন ।

একটি আদর্শ বিশ্বে হ্যাঁ, আপনি সমস্ত কিছু নথিভুক্ত করবেন। তবে পৃথিবীতে আমাদের সময়সীমা, বৈশিষ্ট্য কাটা, পরিবার এবং বন্ধুবান্ধব দেখার জন্য, ছুটি নিতে, দিনে কেবল 24 ঘন্টা এবং বছরে মাত্র 365 দিন রয়েছে। সব কিছু নথিভুক্ত করার জন্য পর্যাপ্ত সময় নেই। সুতরাং, সর্বোত্তমভাবে, আপনি যা কিছু করতে পারেন তা নথি করুন (আপনি সম্পন্ন করবেন না), তবে আপনার বকের জন্য সর্বাধিক ঝাঁকুনি পান:

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

Comments

প্রথমত, যা কিছু বোঝায় না সেগুলি নথিভুক্ত করুন

— ysolik

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

— রায়ান হেইস

@ আইসোলিক আমি সম্মত, তবে আমার মনে হয় তার অর্থ 'ডকুমেন্টে বোঝার জন্য সমস্ত কিছু নথিভুক্ত করা'

— অ্যালান পিয়ারস

@ অ্যালান এবং @ রায়ান: মন্তব্যটি রায়ানকে বিরোধিতা করার উদ্দেশ্যে নয়। এটি শব্দের উপর একটি নাটক ছিল :) বিটিডব্লু, "রায়ান যা বলেছিলেন তার সবকিছুর সাথে আমি একমত," আদর্শ পৃথিবীতে হ্যাঁ, আপনি সমস্ত কিছু নথিভুক্ত করবেন। " একটি আদর্শ বিশ্বে আপনাকে কোনও কিছু ডকুমেন্ট করতে হবে না, কোডটি স্ব-ডকুমেন্টিং এবং স্ব-ব্যাখ্যাকারী হবে।

— ysolik

@ সাইলিক ওহ মানুষ, এটাই হবে চূড়ান্ত আদর্শ বিশ্ব।

— রায়ান হেইস

Answer 2

আপনি অন্য কাউকে কিছু ব্যাখ্যা করার প্রয়োজন অনুভব না করে এটি পড়তে দেখতে পারা পর্যন্ত ডকুমেন্টিং চালিয়ে যান।

Answer 3

এই গত সপ্তাহে ডেইলি ডাব্লুটিএফ-তে ডকুমেন্টেশন সম্পর্কিত একটি দুর্দান্ত নিবন্ধ ছিল । আমি মনে করি এটি সবকিছু বলে, তাই আমি এই লিঙ্কটি ছেড়ে দেব:

http://thedailywtf.com/Articles/Documentation-Done-Right.aspx

মূলত এটি বলে যে এটি কার্যকর হতে না পারলে আপনার কোনও ডকুমেন্ট করা উচিত নয় (কিছু ডকুমেন্টেশন কেবল একটি ড্রয়ারে পচে যেতে বাকী থাকে) এবং প্রকল্পের একটি নির্দিষ্ট অংশ বোঝার জন্য প্রয়োজনীয় ন্যূনতম পরিমাণের তথ্য নথিভুক্ত করুন। খুব বেশি ডকুমেন্টেশন কেবল পাঠককে বিভ্রান্ত করে।

Answer 4

কোডটি পড়ার শ্রোতাদের পক্ষে কোডটি কতটা পঠনযোগ্য তা নির্ভর করে। আপনার কোডটি পড়ার জন্য শ্রোতা কারা, এবং সেই প্রোফাইলের সাথে মিলিত কেউ আপনার কোডটি পড়েন তা চিত্রিত করুন।

আরেকটি উপায় হ'ল এক সপ্তাহ পরে নিজের কোডটি পর্যালোচনা করা এবং আপনি এখনও কী বুঝতে পেরেছেন কিনা তা দেখুন, যদি আপনি না করেন তবে ডকুমেন্টটি তৈরি করুন এবং দুই সপ্তাহ বা তার মধ্যে কোডটি পর্যালোচনা করুন।

Answer 5

আমি যখন একটি পরিষ্কার এবং বিস্তৃত ডকুমেন্টেশনের প্রশংসা করি, স্ব-ডকুমেন্টিং কোডের মতো কিছুই নেই। সুতরাং, নীচের লাইনটি (আমার জন্য) হ'ল:

(উত্স কোড) ডকুমেন্টেশন সম্পর্কে খুব সন্দেহজনক হন; কোডটি উন্নত করে এটিকে অপ্রয়োজনীয় করার চেষ্টা করুন, তবে প্রয়োজনের সময় স্পষ্ট এবং সম্পূর্ণ ডকুমেন্টিং থেকে বিরত থাকবেন না।

অবশ্যই, কিছু পরিস্থিতিতে ডকুমেন্টেশনের প্রয়োজন হতে পারে 'কোডটি কী করছে তা ব্যাখ্যা করা' (যেমন: বৃহত টিম বেস, সংস্থার মানক এবং আরও কিছু)।

Comments

এছাড়াও দেখুন: "মন্তব্যসমূহ একটি কোড গন্ধ হল"

— মশা

Answer 6

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

Answer 7

সাধারণ কথায়, এখন বিকাশকারীদের এবং ভবিষ্যতে রক্ষণাবেক্ষণকারীদের সহায়তা করার জন্য ডকুমেন্টেশন রয়েছে।

যদি আপনি সেই সহজ ম্যাক্সিম মনে করেন তবে ডকুমেন্টেশনের স্তরটি স্ব-সংজ্ঞায়িত হওয়া উচিত।

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

Answer 8

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

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

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

কিছু লোক খালি মন্তব্য যুক্ত করে "ডকুমেন্টেশন বিবেচনা করে" এই আইনটি চিহ্নিত করতে পছন্দ করেন যেখানে তারা নথিপত্র বিবেচনা করেছেন তবে এটি অপ্রয়োজনীয় বলে মনে করেছেন। আমি এই অনুশীলনটি পছন্দ করি না কারণ এটি কোডটি কেবল বিশৃঙ্খলা করে এবং পথে চলে।