রবার্ট সি মার্টিনের উদ্ধৃতিটি প্রসঙ্গের বাইরে নেওয়া হয়েছে। এখানে আরও কিছু প্রসঙ্গের সাথে উদ্ধৃতিটি দেওয়া হয়েছে:
ভালভাবে বসানো মন্তব্য হিসাবে কিছুই তেমন সহায়ক হতে পারে না। অপ্রচলিত কৌতূহলমূলক মন্তব্যের চেয়ে কিছুই মডিউলকে বিশৃঙ্খলা করতে পারে না। পুরানো ক্রুফটি মন্তব্য মিথ্যা এবং ভুল তথ্য প্রচার করার মতো কিছুই তেমন ক্ষতিকারক হতে পারে না।
মন্তব্যগুলি শিন্ডলারের তালিকার মতো নয়। তারা "খাঁটি ভাল" নয়। প্রকৃতপক্ষে, মন্তব্যগুলি সর্বোপরি একটি প্রয়োজনীয় মন্দ। যদি আমাদের প্রোগ্রামিং ভাষাগুলি যথেষ্ট পরিমাণে ভাবপূর্ণ হয়, বা আমাদের অভিপ্রায়টি প্রকাশের জন্য যদি সেই ভাষাগুলির সংক্ষিপ্তভাবে চালিত করার প্রতিভা থাকে তবে আমাদের খুব বেশি মন্তব্যের প্রয়োজন হবে না - সম্ভবত মোটেও নয়।
মন্তব্যে যথাযথ ব্যবহার হ'ল কোডে নিজেকে প্রকাশ করতে ব্যর্থতার ক্ষতিপূরণ দেওয়া। লক্ষ্য করুন যে আমি ব্যর্থতা শব্দটি ব্যবহার করেছি। আমি এটা বোঝাতে চেয়েছিলাম। মন্তব্যগুলি সর্বদা ব্যর্থতা। আমাদের অবশ্যই তাদের থাকতে হবে কারণ এগুলি ছাড়া কীভাবে নিজেকে প্রকাশ করা যায় তা আমরা সবসময়ই বুঝতে পারি না তবে তাদের ব্যবহার উদযাপনের কারণ নয়।
সুতরাং আপনি যখন নিজেকে এমন একটি অবস্থানে খুঁজে পান যেখানে আপনাকে কোনও মন্তব্য লেখার দরকার আছে, তখন এটিটি মনে করে দেখুন এবং সারণীগুলি ঘুরিয়ে দেওয়ার এবং কোডে নিজেকে প্রকাশ করার কোনও উপায় নেই কিনা তা দেখুন। প্রত্যেকবার আপনি কোডে নিজেকে প্রকাশ করার সময় আপনার নিজের পিছনে থাপ্পর দেওয়া উচিত। প্রতিবার আপনি কোনও মন্তব্য লেখার সময়, আপনার মত প্রকাশের দক্ষতার ব্যর্থতা অনুভব করা এবং অনুভব করা উচিত।
( এখান থেকে অনুলিপি করা হয়েছে , তবে মূল উক্তিটি ক্লিন কোড থেকে এসেছে : এন্ডবিল অফ এগ্রিল সফটওয়্যার কারুকাজ )
এই উক্তিটিকে "মন্তব্যগুলি সর্বদা ব্যর্থতা" এ কীভাবে হ্রাস করা হয় এটি একটি উত্তম উদাহরণ যা কিছু লোকেরা কীভাবে প্রজ্ঞার বাইরে একটি বুদ্ধিমান উক্তি গ্রহণ করবে এবং এটিকে বোকামির মতবাদে পরিণত করবে।
এপিআই ডকুমেন্টেশন (জাভাদোকের মতো) এপিআই নথিভুক্ত করার কথা রয়েছে যাতে ব্যবহারকারী উত্স কোডটি না পড়েই এটি ব্যবহার করতে পারে । সুতরাং এই ক্ষেত্রে ডকুমেন্টেশনের পদ্ধতিটি কী করে তা ব্যাখ্যা করা উচিত । এখন আপনি যুক্তি দিতে পারেন যে "এর আইডি দ্বারা একটি পণ্য পুনরুদ্ধার করা" অপ্রয়োজনীয় কারণ এটি ইতিমধ্যে পদ্ধতির নাম দ্বারা ইঙ্গিত করা হয়েছে, তবে যে তথ্য nullফিরে আসতে পারে তা অবশ্যই নথিপত্রের জন্য গুরুত্বপূর্ণ, কারণ এটি কোনওভাবেই সুস্পষ্ট নয়।
আপনি যদি মন্তব্যটির প্রয়োজনীয়তা এড়াতে চান তবে আপনাকে nullএপিআই আরও স্পষ্ট করে অন্তর্নিহিত সমস্যাটি (যা একটি বৈধ রিটার্ন মান হিসাবে ব্যবহার ) মুছে ফেলতে হবে। উদাহরণস্বরূপ আপনি কোনও প্রকারের ফেরত দিতে পারেন Option<Product>, সুতরাং প্রকারের স্বাক্ষরটি নিজেই স্পষ্টভাবে যোগাযোগ করে যে পণ্যটি পাওয়া যায় নি তবে কী ফিরে আসবে।
তবে কোনও অবস্থাতেই কেবল নামগুলির নাম এবং স্বাক্ষরগুলি টাইপ করে কোনও এপিআই সম্পূর্ণ নথিভুক্ত করা বাস্তবসম্মত নয়। ব্যবহারকারীর জানা থাকা কোনও অতিরিক্ত অপ-স্পষ্ট তথ্যের জন্য ডক-মন্তব্যগুলি ব্যবহার করুন। DateTime.AddMonths()ছাত্রলীগ থেকে এপিআই ডকুমেন্টেশন বলুন :
অ্যাডমোথস পদ্ধতিটি লিপ বছরগুলি এবং এক মাসে কত দিনের সংখ্যা গ্রহণ করে ফলাফলের মাস এবং বছর গণনা করে, তারপরে ফলাফলের তারিখটাইম বস্তুর দিনের অংশটি সামঞ্জস্য করে। যদি ফলাফলের দিনটি ফলাফল প্রাপ্ত মাসে কোনও বৈধ দিন না হয় তবে ফলাফল প্রাপ্ত মাসের শেষ বৈধ দিনটি ব্যবহৃত হয়। উদাহরণস্বরূপ, 31 শে মার্চ + 1 মাস = 30 এপ্রিল। ফলাফলের ডেটটাইম অবজেক্টের সময়ের অংশ অংশটি এই উদাহরণ হিসাবে একই থাকে remains
কেবল পদ্ধতির নাম এবং স্বাক্ষর ব্যবহার করে আপনি এটি প্রকাশ করার কোনও উপায় নেই! অবশ্যই আপনার ক্লাস ডকুমেন্টেশনের জন্য এই স্তরের বিশদটির প্রয়োজন নেই, এটি কেবল উদাহরণ an
ইনলাইন মন্তব্যগুলিও খারাপ নয়।
খারাপ মন্তব্য খারাপ। উদাহরণস্বরূপ মন্তব্যগুলির মধ্যে যা কেবল কোড থেকে তুচ্ছভাবে কী দেখা যায় তা ব্যাখ্যা করে, শাস্ত্রীয় উদাহরণটি হ'ল:
// increment x by one
x++;
মতামত যা এমন কিছু ব্যাখ্যা করে যা একটি পরিবর্তনশীল বা পদ্ধতিটির নাম পরিবর্তন করে বা কোডটিকে পুনর্গঠন করে পরিষ্কার করা যেতে পারে, এটি একটি কোড গন্ধ:
// data1 is the collection of tasks which failed during execution
var data1 = getData1();
এর বিরুদ্ধে মার্টিন রেলের মত মন্তব্য। মন্তব্যটি পরিষ্কার কোড লিখতে ব্যর্থতার লক্ষণ - এই ক্ষেত্রে ভেরিয়েবল এবং পদ্ধতির জন্য স্ব-ব্যাখ্যামূলক নাম ব্যবহার করতে। মন্তব্যটি নিজেই অবশ্যই সমস্যা নয়, সমস্যাটি হচ্ছে কোডটি বোঝার জন্য আমাদের মন্তব্যটি প্রয়োজন।
তবে মন্তব্যগুলি কোড থেকে সুস্পষ্ট নয় এমন সমস্ত কিছু বোঝাতে ব্যবহার করা উচিত , উদাহরণস্বরূপ কোডটি কেন একটি নির্দিষ্ট অ-সুস্পষ্ট উপায়ে লেখা হয়েছে:
// need to reset foo before calling bar due to a bug in the foo component.
foo.reset()
foo.bar();
মন্তব্যগুলি যা ব্যাখ্যা করে যে একটি অতিমাত্রায় সংশ্লেষিত কোডের টুকরা কী তা একটি গন্ধও বটে, তবে ফিক্সটি মন্তব্যগুলি বাতিল করা নয়, ফিক্সটি হ'ল কোডটি ঠিক করা! আসল কথায়, সংশ্লেষিত কোডটি ঘটে (আশা করা যায় কেবল অস্থায়ীভাবে একটি রিফ্যাক্টর পর্যন্ত) তবে কোনও সাধারণ বিকাশকারী প্রথমবার নির্ভুল ক্লিন কোডটি লেখেন না। যখন বিভ্রান্তিকর কোডটি ঘটে তখন কোনও মন্তব্য না লেখার চেয়ে এটি কী করে তা ব্যাখ্যা করে একটি মন্তব্য লেখাই অনেক ভাল । এই মন্তব্যটি পরে চুল্লিটি আরও সহজ করে তুলবে।
কখনও কখনও কোড অনিবার্যভাবে জটিল। এটি একটি জটিল অ্যালগরিদম হতে পারে, বা এটি পারফরম্যান্সের কারণে কোডের ত্যাগ স্বচ্ছতার হতে পারে। আবার মন্তব্য করা প্রয়োজন।