মন্তব্য লেখার এবং ডকুমেন্টেশন সেরা অভ্যাস

Question

আজকাল মন্তব্য করা আগের চেয়ে সহজ is জাভাতে, ক্লাসগুলিতে মন্তব্যগুলি যুক্ত করার জন্য কিছু দুর্দান্ত কৌশল রয়েছে এবং জাভা আইডিইগুলি আপনার জন্য মন্তব্য শেল তৈরিতে ভাল। ক্লোজারের মতো ভাষা এমনকি আপনাকে একটি যুক্তি হিসাবে ফাংশন কোডে কোনও ফাংশনের বিবরণ যুক্ত করতে দেয়।

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

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

এমন কোনও উদীয়মান কৌশল রয়েছে যা মন্তব্যগুলিকে বৈধতা দেয় এবং "ফ্লিমি" মন্তব্যগুলি স্বয়ংক্রিয়ভাবে সনাক্ত করে (উদাহরণস্বরূপ যাদুর সংখ্যা, অসম্পূর্ণ বাক্যগুলি ইত্যাদি comments

এবং আরও গুরুত্বপূর্ণ: সেখানে কি "মন্তব্য-নীতিগুলি" বা কৌশলগুলি গ্রহণ করা আছে? কীভাবে কোড দেওয়া যায় সে সম্পর্কে প্রচুর পরামর্শ রয়েছে - তবে "কীভাবে মন্তব্য করবেন?"

Answer 1

• নাম / ডকুমেন্টেশন আপনি যা করছেন তা আপনাকে জানাতে হবে ।

• বাস্তবায়ন আপনাকে কীভাবে করছে তা আপনাকে জানাতে হবে।

• মন্তব্যগুলি আপনাকে বলবে যে আপনি কেন এটি করেন।

Comments

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

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

— ডালিন

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

— র‌্যাচেট ফ্রিক

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

— ক্লার

Answer 2

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

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

Comments

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

— রবার্ট হার্ভে

+1 - আমি আরও মনে করি যে মন্তব্যগুলি কোড কেন লেখা হয়েছে তা ব্যাখ্যা করার জন্যই ব্যবহার করা উচিত । আমি জানি কি if (a == b) then c();করে, তবে কেন এটি হয় তা যদি আমি জানি না - তখনই কোনও মন্তব্য ব্যবহার করা উচিত :)

— ডেকো

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

— দাউদ বলেছেন মনিকা

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

— টেককোজ

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

— মশা

Answer 3

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

Comments

এবং স্পিনিক্স কভারেজ মেট্রিকগুলি সরবরাহ করতে ডকুমেন্টেশনের সাথে কোডের তুলনা করে।

— এস.লট

Answer 4

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

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

যদিও এটি সর্বোত্তম জিনিস যা মন্তব্যগুলি কাঠামোগত করে তোলে, ব্যক্তিগতভাবে আমি অনুভব করি যে কোডকে আরও রক্ষণাবেক্ষণযোগ্য করার জন্য আরও ডকুমেন্টেশন প্রয়োজন। কিছুক্ষণ আগে পি.এসইতে একটি প্রশ্ন ছিল যে ওপেন সোর্স বিকাশকারী সরঞ্জামগুলিতে কোড কী ডকুমেন্টেশন হতে পারে? এটি কত ঘন ঘন হয়? অবশ্যই এটি অন-ওপেন সোর্স প্রকল্পগুলিতেও প্রযোজ্য।

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

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

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

Comments

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

— দাউদ বলেছেন মনিকা

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

— ড্যানমান

Answer 5

এমন কোনও উদীয়মান কৌশল রয়েছে যা মন্তব্যগুলিকে বৈধতা দেয় এবং "ফ্লিমি" মন্তব্যগুলি স্বয়ংক্রিয়ভাবে সনাক্ত করে (উদাহরণস্বরূপ যাদুর সংখ্যা, অসম্পূর্ণ বাক্যগুলি ইত্যাদি comments

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

এবং আরও গুরুত্বপূর্ণ: সেখানে কি "মন্তব্য-নীতিগুলি" বা কৌশলগুলি গ্রহণ করা আছে? কীভাবে কোড করা যায় সে সম্পর্কে প্রচুর পরামর্শ রয়েছে --- তবে "কীভাবে মন্তব্য করবেন?"

"কোড সম্পূর্ণ" তে কীভাবে কোডিং করা যায় তা কেবল নয়, "কীভাবে মন্তব্য করতে হবে", বিশেষত স্ব-ডকুমেন্টিং কোড কীভাবে লিখবেন সে সম্পর্কে অধ্যায়গুলি রয়েছে।

Comments

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

— ম্যাটড্যাভি

Answer 6

জাভা সম্পর্কিত একটি উত্স যা আমি উপভোগ করেছি তা হ'ল জাভাদোক সরঞ্জামের জন্য দস্তাবেজ মন্তব্য কীভাবে লিখবেন ওরাকল এর :

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

এবং আইটেম 44: সমস্ত উন্মুক্ত এপিআই উপাদানগুলির জন্য ডক মন্তব্য লিখুন :

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

থেকে কার্যকর জাভা 2nd সংস্করণ ।