স্ব-ডকুমেন্টিং কোড কী এবং এটি ভাল নথিভুক্ত কোডটি প্রতিস্থাপন করতে পারে? [বন্ধ]

Question

আমার এক সহকর্মী আছেন যারা জোর দিয়ে বলেন যে তার কোডটির মন্তব্য করার দরকার নেই, এটি "স্ব নথিভুক্ত"।

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

আমাকে তার দৃষ্টিভঙ্গি বুঝতে সাহায্য করুন ।

• স্ব ডকুমেন্টিং কোড কী
• এটি কি সত্যিই ভাল মন্তব্য করা এবং ডকুমেন্টেড কোড প্রতিস্থাপন করতে পারে
• এমন কোনও পরিস্থিতি রয়েছে যেখানে এটি নথিভুক্ত ও মন্তব্য করা কোডের চেয়ে ভাল
• এমন কোনও উদাহরণ রয়েছে যেখানে কোড সম্ভবত মন্তব্য ছাড়া স্ব-ডকুমেন্টিং হতে পারে না

হতে পারে এটি কেবল আমার নিজের সীমাবদ্ধতা, তবে কীভাবে এটি একটি ভাল অনুশীলন হতে পারে তা আমি দেখছি না।

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

বাহ, দ্রুত প্রতিক্রিয়া! আপনার উত্তরটি এখানে প্রতিটি উত্তর থেকে যথেষ্ট আলাদা না হলে দয়া করে সমস্ত বিদ্যমান উত্তরগুলি পড়ুন এবং নতুন উত্তর যুক্ত করার পরিবর্তে উত্তরগুলিতে মন্তব্যগুলি সরবরাহ করুন।

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

Comments

আপনি কি জানেন আমাকে সত্যই প্রভাবিত করে? আপনি ছেলেটির সাথে একমত নন তবে আপনি <i> তাকে </ i> বুঝতে চেয়েছেন, তার বিরুদ্ধে আরও গোলাবারুদের জন্য নয়।

— কাজাকো

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

— stinky472

সম্পর্কিত: thedailywtf.com/Articles/…

— কলমারিয়াস

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

— লুৎজ প্রেশেল্ট

আমি এমন ব্যক্তির সাথে কাজ করতাম যিনি সমস্ত কিছুতে বেশি মন্তব্য করেছেন তবে সাধারণত অকেজো মন্তব্য সহ, যেমন i++; // increment i- তবে ফাংশনটির সেই সময়ে কেন i বাড়ানো হবে সে সম্পর্কে কোনও ব্যাখ্যা ছাড়াই ।

— nnnnnn

Answer 1

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

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

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

Comments

এই উত্তরের সাথে সামঞ্জস্য রেখে

— মাসলো

পয়েন্ট এনআর। 3 পয়েন্ট এনআর এর অংশ হওয়া উচিত। 1 আইএমএইচও, যদি কোনও পদ্ধতি এত জটিল হয় যে কোডের বেশ কয়েকটি ব্লকের জন্য উচ্চ বিমূর্ত মন্তব্য প্রয়োজন, কোডের এই জাতীয় ব্লক একটি নতুন পদ্ধতি হওয়া উচিত।

— বার্জার ফ্রেইন্ড-হানসেন 12:25

"1 এর জন্য" এর অর্থ এই নয় যে কোনও মন্তব্য করা উচিত নয় ", যা কিছু লোকের মতামত বলে মনে হয়।

— স্কুরমেডেল

এখনও এই মন্তব্য করার প্রয়োজন নেই : পাবলিক স্ট্যাটিক কালেকশন <ফাইল> ফাইল গ্রেটারথান (ফাইলের পথ, int আকারInBytes);

— চেষ্টা করুন

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

— মেল

Answer 2

ভাল, যেহেতু এটি মন্তব্য এবং কোড সম্পর্কে, আসুন কিছু আসল কোডটি দেখুন। এই সাধারণ কোডটি তুলনা করুন:

float a, b, c; a=9.81; b=5; c= .5*a*(b^2);

এই স্ব-ডকুমেন্টিং কোডটিতে, যা দেখায় যে কী করা হচ্ছে:

const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

এবং তারপরে এই নথিভুক্ত কোডটিতে, এটি কেন এটি করা হচ্ছে তা ভালভাবে ব্যাখ্যা করে:

/* compute displacement with Newton's equation x = vₒt + ½at² */
const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

এবং শূন্য মন্তব্য সহ ডকুমেন্টেশন হিসাবে কোডের চূড়ান্ত সংস্করণ :

float computeDisplacement(float timeInSeconds) {
    const float gravitationalForce = 9.81;
    float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);
    return displacement;
}

দরিদ্র মন্তব্য করার শৈলীর উদাহরণ এখানে:

const float a = 9.81; //gravitational force
float b = 5; //time in seconds
float c = (1/2)*a*(b^2) //multiply the time and gravity together to get displacement.

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

আমি বলব যে এটি আপনি কী করছেন এর প্রসঙ্গে নির্ভর করে। আমার কাছে, স্ব-ডকুমেন্টেড কোড সম্ভবত এই ক্ষেত্রে যথেষ্ট, তবে কী করা হয়েছে তার পিছনে পদ্ধতিটির বিশদ সম্পর্কিত একটি মন্তব্য (এই উদাহরণস্বরূপ, সমীকরণ )ও দরকারী।

Comments

পুরো

— অংশটি

হ্যাঁ, ফাংশন স্থানচ্যুতি ডিউটোগ্রাভিটি (ইনটাইম ইনসেকেন্ডস, ফ্লোট গ্র্যাভিটেশনাল অ্যাকসিলারেশন = 9.81) আমার পক্ষে পড়া সহজ হবে।

— ক্রিশ্চিয়ান রোমো

আমি এখানে একটি মন্তব্য মিস করছি: 5 সেকেন্ড কেন?

— জন নিলসন

বর্ণনামূলক ফাংশন নামের জন্য আর একটি ভোট। এটি নিজেই সমীকরণ দেয় না তবে আমি এটি দেখতে চাই না।

— লরেন পেচটেল

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

— নিক

Answer 3

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

Comments

একমত। যদিও মাঝেমধ্যে সর্বোত্তম কোডটিও এর চূড়ান্ত প্রভাবটি লুকিয়ে রাখতে পারে তবে মন্তব্যে কেন এটির উত্তর দিয়ে এটি পরিচালনা করা হয়। যেমন রয়েছে, "আপনি কেন এইভাবে 5 টি ভেরিয়েবল পরিবর্তন করেছিলেন?"

— স্যাম এরউইন

আমার 2 সেন্ট: [ইউনিট, স্পেক, আচরণ,] কেস "পৃথিবীতে কেন" কিছুটা উত্তর নেই? তারপরে আপনি পরীক্ষার কেসটি পড়তে পারেন এবং কেন এটির উদ্দেশ্য দেওয়া উচিত।

— জোনকে

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

— tsellon

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

— ড্রাগন

@ সিসলন, আপনার স্বয়ংক্রিয় স্পেক আপনাকে তা বলতে পারে এবং এটি কার্যকর কোড যা প্রয়োগকারী কোডটি পরীক্ষা করে। সুতরাং যদি বাস্তবায়নটি কোনওরকম পরিবর্তিত হয়, তবে চক্রটি ভেঙে যায়। কত সুন্দর? মন্তব্যগুলি যা আপনাকে সতর্ক করে দেয় যখন বাস্তবায়ন কোডটি মন্তব্যটি আর নির্দিষ্ট করে কী করে না?

— প্রগমেটিক এগ্রিলিস্ট

Answer 4

কেউ একবার বলেছিলেন

1) কেবল কোডের জন্য মন্তব্য লিখুন যা বোঝা শক্ত।
2) বোঝার জন্য যে কোড লিখতে না চেষ্টা করুন।

Comments

কোডটি লেখার সময় আপনার কাছে যা বোঝার জন্য তুচ্ছ মনে হয় তা আসলে অন্য কারও পক্ষে পরে বুঝতে খুব কঠিন হতে পারে, এমনকি যদি কেউ অন্য কয়েক মাস / বছরে আসলেই থাকেন।

— অ্যান্ডার্স স্যান্ডভিগ

আমি প্রায়শই শুক্রবারে লেখা জিনিসগুলি সোমবার সকালে

— কুঁচকে ফেলার

যা আমাদের "মন্তব্য লেখার চেষ্টা না করার" দিকে পরিচালিত করে

— মুস্তাফাবর

Answer 5

"স্ব-ডকুমেন্টিং" কোডের পিছনে ধারণাটি হ'ল কোডটিতে আসল প্রোগ্রামের যুক্তি তুচ্ছভাবে পরিষ্কারভাবে কোড পড়ার যে কাউকে কেবল কোডটি কী করছে তা নয় তা কেন করছে তা ব্যাখ্যা করার জন্য clear

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

Comments

আইএমএইচও ব্লকটি আপনাকে কীভাবে , ফাংশনের নামটি কেন তা আপনাকে জানাতে হবে । যতক্ষণ আপনি উভয়কে একসাথে ব্যবহার করেন ততক্ষণ আপনি অভিপ্রায় এবং বাস্তবায়ন উভয়ই প্রকাশ করেন .... int GetBoundingBox() {return CalcContentDimensions() + this.padding + this.margin;}...

— বেসিক

Answer 6

আমি মনে করি এটি কোডের কোনও নির্দিষ্ট লাইনটি স্ব-ডকুমেন্টিং কিনা তা প্রশ্নের সাথে প্রাসঙ্গিক বলে মনে হয় তবে শেষ পর্যন্ত যদি আপনি কোডের কোনও স্লাইসের গঠন এবং কার্যকারিতা বুঝতে না পারেন তবে বেশিরভাগ সময় মন্তব্যগুলি সহায়তা করবে না। উদাহরণস্বরূপ, আমডফানের "সঠিকভাবে মন্তব্য করা" কোডের টুকরোটি ধরুন:

/* compute displacement with Newton's equation x = v0t + ½at^2 */
const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

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

const float accelerationDueToGravity = 9.81;
float timeInSeconds = 5;
float displacement = NewtonianPhysics.CalculateDisplacement(accelerationDueToGravity, timeInSeconds);

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

Comments

আপনার আরও বেশি পরিমাণে প্রয়োজন, আপনার উদাহরণটি ব্যাখ্যা করে যে আমাদের কেন ডকুমেন্টের জন্য ফাংশন নাম ব্যবহার করা উচিত।

— এপি-ইনাগো

Answer 7

আমি এটি কোথা থেকে পেয়েছি তা ভুলে গিয়েছি তবে:

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

Comments

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

— স্কট ডরম্যান

যদি দুটি যথাযথ সঠিক পদ্ধতি থাকে তবে আপনি কেন অন্যটির থেকে একটি বেছে নিলেন তা বিবেচ্য নয়?

— ইবিগ্রিন

হ্যাঁ, সমানভাবে সঠিক অর্থ হুবহু একই একই নয় not একটি পদ্ধতি অন্য পরিস্থিতিতে কিছু পরিস্থিতিতে দ্রুত হতে পারে।

— ইক্কে

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

— ইবিগ্রিন

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

— ইবিগ্রিন

Answer 8

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

স্ব-ডকুমেন্টিং কোড হ'ল এমন কোড যা কোনও জ্ঞাত পাঠকের জন্য এটি কী করছে তা বোঝার জন্য ফ্রি-টেক্সট মন্তব্যের প্রয়োজন হয় না। উদাহরণস্বরূপ, কোডের এই অংশটি স্ব-ডকুমেন্টিং:

print "Hello, World!"

এবং তাই এটি:

factorial n = product [1..n]

এবং তাই এটি:

from BeautifulSoup import BeautifulSoup, Tag

def replace_a_href_with_span(soup):
    links = soup.findAll("a")
    for link in links:
        tag = Tag(soup, "span", [("class", "looksLikeLink")])
        tag.contents = link.contents
        link.replaceWith(tag)

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

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

Answer 9

স্ব-ডকুমেন্টিং কোডটি "DRY" (নিজেকে পুনরাবৃত্তি করবেন না) এর একটি ভাল উদাহরণ example কোডগুলিতে যা হয় বা হতে পারে এমন মন্তব্যে তথ্য নকল করবেন না।

ভেরিয়েবল কী জন্য ব্যবহৃত হয় তা ব্যাখ্যা করার পরিবর্তে ভেরিয়েবলটির নতুন নামকরণ করুন।

কোডের একটি সংক্ষিপ্ত স্নিপেট কী করে তা ব্যাখ্যা করার পরিবর্তে এটিকে একটি পদ্ধতিতে বের করুন এবং এটি বর্ণনামূলক নাম দিন (সম্ভবত আপনার মন্তব্য পাঠ্যের একটি সংক্ষিপ্ত সংস্করণ)।

জটিল পরীক্ষা কী করে তা ব্যাখ্যা করার পরিবর্তে এটি একটি পদ্ধতিতেও বের করুন এবং এটি একটি ভাল নাম দিন।

প্রভৃতি

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

এর অর্থ এই নয় যে আপনার কোনও মন্তব্য নেই, এমন কিছু তথ্য রয়েছে যা আপনি কোডে রাখতে পারবেন না যেমন অভিপ্রায় সম্পর্কিত তথ্য ("কেন")। আদর্শ ক্ষেত্রে কোড এবং মন্তব্যগুলি একে অপরের পরিপূরক, প্রতিটি একে অপরের তথ্য নকল না করে অনন্য বর্ণনামূলক মান যুক্ত করে।

Comments

একটি ব্যতিক্রম: খারাপ প্রোগ্রামাররা। আমি মন্তব্যগুলি দেখেছি কোড বলছে এমন কিছু করছে যা এটি নয়। তারপরে আমি নিজেকে জিজ্ঞাসা করি: আমি কোডটি বা মন্তব্যটি ঠিক করব?

— গুজে

আপনি উদ্দেশ্য-সি তে পদ্ধতির নামগুলি বীট করতে পারবেন না। :)

Answer 10

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

এই কথাটি বলার পরে, মন্তব্যগুলি নতুন আগতদের জন্য বা পরীক্ষকদের জন্য বা ডকুমেন্টেশন / সহায়তা ফাইলগুলি তৈরি করতে খুব সহায়ক হতে পারে।

স্ব-ডকুমেন্টিং কোড + প্রয়োজনীয় মন্তব্যগুলি টিম জুড়ে লোকদের সহায়তা করার জন্য দীর্ঘ পথ পাবে।

Answer 11

ক্রমানুসারে:

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

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

Comments

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

— ওয়েজ

পদ্ধতির নামগুলি মিথ্যা বলতে পারে এবং এটিও পুরানো হতে পারে।

— কলমারিয়াস

Answer 12

আপনি যখন একটি "স্ব-ডকুমেন্টিং কোড" পড়েন, আপনি দেখেন এটি কী করছে তবে আপনি কেন সবসময় অনুমান করতে পারবেন না যে এটি কেন সেই বিশেষ উপায়ে করছে।

ব্যবসায়ের যুক্তি, সুরক্ষা, ব্যবহারকারীর চাহিদা ইত্যাদির মতো নন-প্রোগ্রামিং সীমাবদ্ধতা রয়েছে tons

আপনি যখন রক্ষণাবেক্ষণ করেন, সেই ব্যাকগোন্ডের তথ্যগুলি খুব গুরুত্বপূর্ণ হয়ে ওঠে।

শুধু আমার চিমটি লবণ ...

Answer 13

একটির জন্য, নিম্নলিখিত স্নিপেট বিবেচনা করুন:

/**
 * Sets the value of foobar.
 *
 * @foobar is the new vaue of foobar.
 */
 public void setFoobar(Object foobar) {
     this.foobar = foobar;
 }

এই উদাহরণে আপনার কাছে কোডের 3 টি লাইনে 5 টি লাইনের মন্তব্য রয়েছে। আরও খারাপ - মন্তব্যগুলি এমন কোনও কিছু যুক্ত করে না যা আপনি কোডটি পড়ে দেখেন না। আপনার যদি 10 টি মতো পদ্ধতি থাকে তবে আপনি 'মন্তব্য অন্ধত্ব' পেতে পারেন এবং প্যাটার্ন থেকে বিচ্যুত এক পদ্ধতিটি লক্ষ্য করতে পারেন না।

অবশ্যই যদি এর থেকে আরও ভাল সংস্করণটি হত:

/**
 * The serialization of the foobar object is used to synchronize the qux task.
 * The default value is unique instance, override if needed.
 */
 public void setFoobar(Object foobar) {
     this.foobar = foobar;
 }

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

Comments

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

— জেমস ম্যাকমাহন

Answer 14

"কী" এবং "কীভাবে" এর মধ্যে পার্থক্য রয়েছে।

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

Comments

দৃঢ়ভাবে অসম্মতি. একটি রুটিন কী করে তা নাম থেকেই সুস্পষ্ট হওয়া উচিত। এটি কী করে তা বাস্তবায়ন কোড থেকে সুস্পষ্ট হওয়া উচিত। বাস্তবায়ন কেন এটি লিখিত ছিল তা নথিভুক্ত করা উচিত ।

— অ্যান্থনি ম্যানিং-ফ্র্যাঙ্কলিন

Answer 15

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

Comments

আপনি এটিকে একটি নিয়ম হিসাবে গ্রহণ করেন এবং আপনি আপনার কোডবেজে পাঠ্যপুস্তকটি লেখার শেষ করবেন ;-) যদিও আমি অ-সুস্পষ্ট সিদ্ধান্তের জন্য সম্মত।

— ddimitrov

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

— ওনোরিও ক্যাটানাচি

লিখিত ছিল না যে কোড নথি ! :)

— টনি

Answer 16

এমন একটি সংস্থায় যেখানে আমি একজন প্রোগ্রামার কাজ করেছি তার মনিটরের শীর্ষে নিম্নলিখিতটি আটকে ছিল।

"আপনার কোডটি নথিভুক্ত করুন এমন ব্যক্তির মতো যিনি এটি বজায় রাখেন এমন একটি সমকামী পাগল, যিনি জানেন আপনি কোথায় থাকেন" "

Answer 17

স্ব-ডকুমেন্টিং কোড সাধারণত ভেরিয়েবলের নাম ব্যবহার করে যা কোডটি ঠিক কী করে চলেছে তার সাথে মেলে যাতে কী চলছে তা বোঝা সহজ

যাইহোক, এই জাতীয় "স্ব-ডকুমেন্টিং কোড" মন্তব্যগুলি প্রতিস্থাপন করবে না will কখনও কখনও কোডটি খুব জটিল এবং স্ব-ডকুমেন্টিং কোড যথেষ্ট নয়, বিশেষত রক্ষণাবেক্ষণের পথে।

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

Comments

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

— টিগ্রেন

একটি নির্দিষ্ট বাস্তবায়ন, অ্যালগরিদম বা সূত্র কেন অন্য একটি সমানভাবে সঠিক হিসাবে বেছে নেওয়া হয়েছিল তা বাদে। কোনও কোড কোডে কেন করা হয়েছিল তা আপনি কখনই বর্ণনা করতে পারবেন না, কেবল সেই পছন্দটি কী।

— স্কট ডরম্যান

@ স্কট: আপনি উভয় বিকল্পকে একটি বৃহত্তর শ্রেণীর অধীনে রাখতে পারেন এবং অন্যটিকে অপরিবর্তিত রেখে যেতে পারেন সম্পর্কে মন্তব্য করার সাথে ... ওহ অপেক্ষা করুন।

— এপি-ইনাগো

Answer 18

আমি আশ্চর্য হয়েছি যে কেউ " ল্যাট্রেট প্রোগ্রামিং " নিয়ে আসে নি , এটি একটি প্রযুক্তি টেক্সের ডোনাল্ড ই নুথ এবং "দ্য আর্ট অফ কম্পিউটার প্রোগ্রামিং" খ্যাতির 1981 সালে বিকশিত হয়েছিল।

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

সাহিত্যের প্রোগ্রামিং সরঞ্জামগুলি আপনাকে কোনও দস্তাবেজের জন্য বিশেষ মার্কআপ দিয়ে এটি করে যা সরঞ্জামগুলি কী অংশটি উত্স হওয়া উচিত এবং কোনটি পাঠ্য তা বলে। প্রোগ্রামটি পরে নথির বাইরে থেকে সোর্স কোড অংশগুলি ছিঁড়ে ফেলে একটি কোড ফাইল একত্রিত করে।

আমি এর ওয়েবে একটি উদাহরণ পেয়েছি: http://moonflare.com/code/select/select.nw বা এইচটিএমএল সংস্করণ http://moonflare.com / কোড / নির্বাচন / বেছে নিন html

যদি আপনি নুথের বইটি কোনও লাইব্রেরিতে খুঁজে পান (ডোনাল্ড ই নূথ, সাহিত্যের প্রোগ্রামিং, স্ট্যানফোর্ড, ক্যালিফোর্নিয়া: সেন্টার ফর স্টাডি অফ ল্যাঙ্গুয়েজ অ্যান্ড ইনফরমেশন, 1992, সিএসএলআই লেকচার নোটস, নং ২.।) আপনার এটি পড়া উচিত।

এটি স্ব-ডকুমেন্টিং কোড, যুক্তি এবং সমস্ত সহ সম্পূর্ণ। এমনকি একটি দুর্দান্ত দস্তাবেজ তৈরি করে, সমস্ত কিছুই কেবল ভালভাবে লেখা মন্তব্যগুলি :-)

Comments

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

— গুজ

Answer 19

আমি অনেকগুলি বৈধ উত্তরের জন্য আরও একটি দৃষ্টিভঙ্গি দিতে চাই:

উত্স কোড কী? প্রোগ্রামিং ভাষা কী?

মেশিনগুলির উত্স কোডের প্রয়োজন নেই। তারা সমাবেশ সমাবেশ খুশি। প্রোগ্রামিং ভাষাগুলি আমাদের সুবিধার জন্য। আমরা সমাবেশ লিখতে চাই না। আমরা কী লিখছি তা আমাদের বুঝতে হবে। প্রোগ্রামিং কোড লেখার বিষয়ে is

আপনি যা লিখবেন তা কি পড়তে হবে?

উত্স কোড মানব ভাষায় লেখা হয় না। এটি চেষ্টা করা হয়েছে (উদাহরণস্বরূপ ফরটারান) তবে এটি সম্পূর্ণ সফল নয়।

উত্স কোডে অস্পষ্টতা থাকতে পারে না। এজন্য পাঠ্যের সাথে আমাদের তুলনায় আমাদের আরও কাঠামো রাখতে হবে। পাঠ্যটি কেবল প্রসঙ্গের সাথে কাজ করে, যা আমরা পাঠ্য ব্যবহার করার সময় মঞ্জুর করি। উত্স কোডে প্রসঙ্গটি সর্বদা প্রকাশিত হয়। সি # তে "ব্যবহার করে" ভাবুন।

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

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

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

তবে প্রতিটি প্রকল্পে জটিলতা লুকিয়ে থাকে, জটিলতাটি কোথায় রাখবেন এবং কোনটি উটকে গ্রাস করতে হবে তা আপনাকে সর্বদা সিদ্ধান্ত নিতে হবে। মন্তব্যগুলি ব্যবহারের জন্য সেগুলি।

Answer 20

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

আমার জন্য, আমি এই নিয়মগুলি অনুসরণ করার চেষ্টা করি:

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

এর অর্থ হ'ল ডকুমেন্টিং কোডের তিনটি মাধ্যমই এক সাথে কাছাকাছি বাস করে এবং তাই কোড পরিবর্তিত হওয়ার সাথে সাথে পরিবর্তিত হওয়ার সম্ভাবনা বেশি থাকে তবে তারা যা প্রকাশ করে তাতে ওভারল্যাপ না করে।

Answer 21

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

তবে ডকুমেন্টেশনের ক্ষেত্রে যা গুরুত্বপূর্ণ তা হ'ল এমন উপাদান যা কোড থেকে সরাসরি স্পষ্ট হয় না: অন্তর্নিহিত অভিপ্রায়, অনুমান, প্রভাব, সীমাবদ্ধতা ইত্যাদি is

কোনও কোড ওয়াই করে না তা নির্ধারণ করতে সক্ষম হওয়ার চেয়ে কোনও কোডকে তাত্ক্ষণিকভাবে X করে তোলে তা নির্ধারণ করতে সক্ষম হওয়া He তাকে Y নথিভুক্ত করতে হবে ...

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

Answer 22

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

এটি যদিও আপনার ডকুমেন্টেশনগুলিকে সত্যিকার অর্থে প্রতিস্থাপন করতে পারে না, কারণ ডকুমেন্টেশন হ'ল আপনি কীভাবে আপনার সিস্টেমকে কীভাবে ব্যবহার করবেন তা ব্যাখ্যা করার জন্য অন্যকে দেয় যা এটি কীভাবে কাজ করে।

সম্পাদনা করুন: আমার (এবং সম্ভবত সকলের) সম্ভবত এই বিধান থাকা উচিত যে একটি ডিজিটাল সিগন্যাল প্রসেসিং (ডিএসপি) অ্যাপটি খুব ভালভাবে মন্তব্য করা উচিত। এটি মূলত কারণ ডিএসপি অ্যাপ্লিকেশনগুলি মূলত অ্যারেগুলিতে খাওয়ানো লুপগুলির জন্য মূলত 2 এবং যোগ / গুণ / ইত্যাদি বলে মানগুলি ... প্রোগ্রামটিকে পরিবর্তন করতে আপনি কোনও অ্যারেতে মানগুলি পরিবর্তন করেন ... কি বলতে কিছু মন্তব্য দরকার আপনি সেই ক্ষেত্রে করছেন;)

Comments

সুতরাং কোনও ফাংশন বা ভেরিয়েবল নাম একটি সমস্যা সমাধানের জন্য দুটি বা ততোধিক সমানভাবে সঠিক উপায়ে কেন অন্য একটির প্রয়োগ বাস্তবায়নের জন্য বেছে নেওয়া হয়েছিল তা ব্যাখ্যা করার জন্য যথেষ্ট তুচ্ছ স্পষ্ট প্রসঙ্গ সরবরাহ করবে?

— স্কট ডরম্যান

Answer 23

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

আমি আমার কোডটি যথাসম্ভব স্ব-ডকুমেন্টিং করার চেষ্টা করি, তবে কয়েক মাস পরে আমি যখন এটিতে আবার কাজ করতে ফিরে আসি, তখন এটিকে একটি হ্যাশ তৈরি করা থেকে বিরত রাখতে সত্যই আমার ব্যাখ্যাটি পড়তে হবে।

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

তবে প্রচুর কোডের বোধগম্য হওয়ার জন্য কমেন্টের দরকার নেই, তাই এটিকে যথাসম্ভব স্পষ্ট করে লিখুন এবং তারপরে যতগুলি মন্তব্য প্রয়োজন তেমন ব্যবহার করুন ...

Answer 24

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

ভাল ডোমেন মডেলিং 
+ ভাল নাম (বৈচিত্র, পদ্ধতি, ক্লাস) 
কোড উদাহরণ (ব্যবহারের ক্ষেত্রে ইউনিট পরীক্ষা) 
= স্ব নথিভুক্ত সফ্টওয়্যার 

Answer 25

কোড ছাড়াও অতিরিক্ত মন্তব্য কেন পরিষ্কার হতে পারে তার কয়েকটি কারণ:

• আপনি যে কোডটি দেখছেন সেটি স্বয়ংক্রিয়ভাবে তৈরি হয়েছিল এবং তাই পরবর্তী সময়ে প্রকল্পটি সংকলনের সময় কোডটিতে কোনও সম্পাদনা ক্লোবারড হতে পারে
• পারফরম্যান্স লাভের জন্য স্বল্প-সহজ-সরল বাস্তবায়ন কেনাবেচা করা হয়েছিল (একটি লুপকে তালিকাভুক্ত করা, ব্যয়বহুল গণনার জন্য দেখার টেবিল তৈরি করা ইত্যাদি))

Answer 26

দলটি তার ডকুমেন্টেশনে কী মূল্য দেয় এটি সব হতে চলেছে। আমি পরামর্শ দিচ্ছি যে কীভাবে / ইন্টেন্টের পরিবর্তে গুরুত্বপূর্ণ এবং এটি সর্বদা স্ব ডকুমেন্টিং কোডে ধরা পড়ে না তার পরিবর্তে ডকুমেন্টিং। get / set এগুলি সুস্পষ্ট নয় - তবে গণনা, পুনরুদ্ধার ইত্যাদি কেন প্রকাশ করা উচিত।

আপনি যদি বিভিন্ন জাতীয়তা থেকে আগত হন তবে আপনার দলে পার্থক্য সম্পর্কে সচেতন হন। কথাসাহিত্যের মধ্যে পার্থক্য পদ্ধতিগুলির নামকরণের জন্য ক্রিয়া করতে পারে:

BisectionSearch

BinarySearch

BinaryChop

3 টি বিভিন্ন মহাদেশে প্রশিক্ষণপ্রাপ্ত বিকাশকারীদের এই তিনটি পদ্ধতি একই কাজ করে। কেবলমাত্র অ্যালগরিদম বর্ণিত মন্তব্যগুলি পড়ে আমরা আমাদের লাইব্রেরিতে নকলটি সনাক্ত করতে সক্ষম হয়েছি।

Answer 27

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

কোডটি লেখা সহজ হয় যা এটি যা করে তা স্ব-দলিল করে। এটি কেন এমন মন্তব্য বেশি উপযুক্ত তা আপনাকে জানাতে, তবে এখানে কোড আরও ভাল হতে পারে। আপনি যদি বিমূর্ততার প্রতিটি স্তরে আপনার সিস্টেমটি বুঝতে পারেন তবে আপনার নিজের কোডটি সাজানোর চেষ্টা করা উচিত

public Result whatYouWantToDo(){
  howYouDoItStep1();
  howYouDoItStep2();
  return resultOfWhatYouHavDone;
}

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

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

Answer 28

বেশিরভাগ ডকুমেন্টেশন / মন্তব্যগুলি ভবিষ্যতে কোড বর্ধক / বিকাশকারীদের কোডকে রক্ষণাবেক্ষণযোগ্য করে তুলতে সহায়তা করে। প্রায়শই না হয় আমরা পরে আবার নতুন বৈশিষ্ট্য যুক্ত করতে বা অনুকূল করতে আমাদের মডিউলটিতে ফিরে আসি। সেই সময়ে অসংখ্য ব্রেকপয়েন্টগুলির মধ্যে পদক্ষেপের চেয়ে কমেন্টগুলি সহজভাবে পড়ার দ্বারা কোডটি বোঝা সহজ হবে। তদতিরিক্ত আমি বিদ্যমান কৌশলটি বোঝার চেয়ে বরং নতুন যুক্তির জন্য চিন্তা করতে সময় ব্যয় করব।

Answer 29

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

এর অর্থ এই নয় যে কোডটি মন্তব্য করা উচিত নয়। এর অর্থ হল যে কোডগুলি কেন এভাবে লেখা হচ্ছে তা মন্তব্যগুলির একটি কারণ প্রদান করা উচিত।

Answer 30

আমি বিশ্বাস করি যে স্ব-ডকুমেন্টিং কোড অর্জনের জন্য আপনার সর্বদা প্রচেষ্টা করা উচিত কারণ এটি কোড পড়া সহজ করে তোলে। যাইহোক, আপনি জিনিস সম্পর্কে ব্যবহারিক হতে হবে।

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

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

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