মন্তব্যগুলি কি ডকুমেন্টেশনের ফর্ম হিসাবে বিবেচিত হয়?

Question

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

এটি না:

$foo = "bar"; # this is a comment
print $foo; # this prints "bar"

ডকুমেন্টেশন হিসাবে বিবেচনা করা হবে, বিশেষত যদি কোনও বিকাশকারী আমার কোড ব্যবহার করছেন? বা ডকুমেন্টেশন কোডের বাইরেই বিবেচনা করা হয়?

Comments

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

— রোবটটি

ইয়াঙ্গনি ( xprogramming.com / অনুশীলন / প্র্যাকনটনিড । Html )। আপনার সন্তুষ্টি আপনার কোড নথি। গ্রাহককে (যদি সেখানে কখনও থাকে) তাদের সন্তুষ্টির জন্য ডকুমেন্টেশন লেখার জন্য আপনাকে অর্থ প্রদান করুন। আপনি প্রচুর লোক কী বলতে চান তা নিয়ে চিন্তা করবেন না (যদি না তারা আপনাকে অর্থ প্রদান করে)।

— এমরি

আপনার 2 টি মন্তব্যের মধ্যে ২ য় মন্তব্য অকেজো, কেন with foo বারের সাথে প্রতিস্থাপন করবেন না। এটি যদি সত্য না হয় তবে মন্তব্যটি ভুল। প্রথম মন্তব্যটি ভুল। এটি একটি কাজ।

— ctrl-alt-delor

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

— ctrl-alt-delor

ইয়াংনি কি "আপনার প্রয়োজন হবে না"

— ক্রিস এস

Answer 1

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

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

Comments

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

— এডওয়ার্ড স্ট্রেঞ্জ

আমি সত্যই এর সাথে একমত নই, আপনার কাছে কেবলমাত্র নির্ভরযোগ্য ডকুমেন্টেশন হ'ল সোর্স কোড code মন্তব্য এবং "ডকুমেন্টেশন" উভয়ই কোড সহ বজায় রাখতে হবে, যা খুব কমই ঘটে। সুতরাং ডকুমেন্টেশনের একমাত্র নির্ভরযোগ্য উত্স হল আপনার কোড!

— মার্টিয়ার্ট

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

— ওলেকসি

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

— ডোনাল ফেলো

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

— স্টিভেন ইভার্স

Answer 2

এগুলি ডকুমেন্টেশনের একটি রূপ, তবে মনে রাখবেন যে ডকুমেন্টেশনটি দর্শকের চোখে পড়ে ....

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

• সোর্স কোডটি খুঁজছেন তবে কম প্রযুক্তিগত দক্ষতার সাথে, মন্তব্যগুলি ঠিক থাকতে পারে। তবে ধরে নেওয়া হয়েছে যে কেউ সোর্স কোডের দিকে তাকিয়ে আছে।

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

• যদি ব্যবহারকারীর প্রযুক্তিগত দক্ষতা না থাকে তবে কেবল কী হচ্ছে তা জানতে হবে, ব্যবহারকারীর ডকুমেন্টেশন যা প্রয়োজন তা হল।

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

Comments

স্ব ডকুমেন্টিং কোড একটি মিথ্যা।

— ইন্নিস

@ ইউনিসিজোরোস সম্পূর্ণ মিথ্যা বলার চেয়েও অপ্রাপ্তিযোগ্য গোলের মতো।

— পাথারিনের শিখা

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

— ডক ব্রাউন

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

— ইয়ান্নিস

@ ম্যাথএট্যাক সর্বাধিক শালীন আইডিই মন্তব্যগুলিকে আড়াল / ভাঁজ করতে পারে। তবে হ্যাঁ, কখনও কখনও তারা কেবল পথে যায়।

— ইন্নিস

Answer 3

হ্যাঁ, মন্তব্যগুলি ডকুমেন্টেশনের একটি ফর্ম। আপনার কোডটি বজায় রাখতে বা আপডেট করতে হবে এমন কারও পক্ষে তারা দরকারী ডকুমেন্টেশন হ'ল না তা একটি মুক্ত প্রশ্ন।

আমি জানি আপনি এটিকে ছুড়ে ফেলা উদাহরণ হিসাবে বোঝাতে চেয়েছিলেন তবে স্টাফ পছন্দ

print $foo; # this prints "bar"

দরকারী নয়; এটি কেবল ভিজ্যুয়াল বিশৃঙ্খলা যুক্ত করে। সুস্পষ্ট দলিল করবেন না।

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

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

Answer 4

আমি ক্লিন কোড থেকে বব মার্টিনের এই দৃষ্টিভঙ্গির সাথে আঁকড়ে ধরেছি বলে মনে হয় সাধারণত আপনি নিজেরাই মন্তব্য করছেন বা মন্তব্য করছেন এবং ডকুমেন্টেশন ছেড়ে যাচ্ছেন না বলে এই সমস্যাটি সমাধান করে:

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

... লেখার তুলনায় বনাম সময় ব্যয় করার অনুপাত 10: 1 এরও বেশি। আমরা নতুন কোড লেখার প্রচেষ্টার অংশ হিসাবে ক্রমাগত পুরানো কোডটি পড়ছি।

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

Answer 5

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

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

Comments

সত্যই কৌতুকপূর্ণ জিনিসগুলি একটি একাডেমিক কাগজে (বা, কখনও কখনও, পেটেন্ট) থাকা উচিত।

— ডোনাল ফেলো

Answer 6

মন্তব্যগুলি ডকুমেন্টেশনের একটি ফর্ম। একটি নিকৃষ্ট ফর্ম এবং একটি যা আপনাকে পরামর্শ দেয় যে আপনার কোডের এমন একটি অঞ্চল রয়েছে যা আরও ভাল ফ্যাক্টর করা যায়।

দেখে মনে হচ্ছে আপনি বাধ্যতামূলকভাবে মন্তব্য করেছেন। অন্যান্য বিকল্প থাকা ভাল জিনিস হতে পারে। আমি ডকুমেন্টেশনের তিনটি সেরা ফর্ম সম্পর্কে ভাবতে পারি:

1) আপনার কোড আরও ভাল ফ্যাক্টর। কোনও মন্তব্য যুক্ত করার পরিবর্তে, একটি পদ্ধতি বা ফাংশনটি বের করুন যার নাম আপনি যে মন্তব্যটি লিখতে চলেছেন তার পাঠ্য। কোডটি আপনার মন্তব্য বলতে যাচ্ছিল তা বলে।

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

3) স্ক্রিপ্টগুলির জন্য, --help বিকল্প। আপনি এখানে নথিতে বাদাম যেতে পারেন। উদাহরণগুলিতে থাকুন, ব্যবহারকারী কী প্রয়োজন তা অনুমান করুন।

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