ইনলাইন কোড মন্তব্যের জন্য সেরা পদ্ধতির কী?

আমরা ২০ বছরের পুরনো লিগ্যাসি কোডবেজে কিছুটা রিফ্যাক্টরিং করছি, এবং আমি কোডে মন্তব্যগুলির বিন্যাস সম্পর্কে আমার সহকর্মীর সাথে আলোচনা করছি (plsql, java)।

মন্তব্যের জন্য কোনও ডিফল্ট ফর্ম্যাট নেই, তবে বেশিরভাগ ক্ষেত্রে লোকেরা মন্তব্যে এমন কিছু করেন:

// date (year, year-month, yyyy-mm-dd, dd/mm/yyyy), (author id, author name, author nickname) and comment

আমি চাই ভবিষ্যতের এবং অতীতের মন্তব্যগুলির জন্য প্রস্তাবিত ফর্ম্যাটটি হ'ল:

// {yyyy-mm-dd}, unique_author_company_id, comment

আমার সহকর্মী বলেছেন যে আমাদের কেবল মন্তব্যটি প্রয়োজন, এবং অবশ্যই এই ফর্ম্যাটটিতে সমস্ত অতীত এবং ভবিষ্যতের মন্তব্যগুলি পুনরায় ফর্ম্যাট করতে হবে:

// comment

আমার যুক্তি:

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

আমার সহকর্মীর যুক্তি:

ইতিহাস এসসিএম-এ রয়েছে
বিকাশকারীদের অবশ্যই কোডে সরাসরি ইতিহাসের ইতিহাস সম্পর্কে অবগত থাকতে হবে না
প্যাকেজগুলি 15k লাইন লম্বা হয় এবং কাঠামোগত মন্তব্যগুলি এই প্যাকেজগুলি বোঝা আরও শক্ত করে তোলে

আপনি কি সেরা পদ্ধতির মনে করেন? অথবা এই সমস্যাটি সমাধান করার জন্য আপনার আরও ভাল পদ্ধতির কী আছে?

— দিয়েগো আলভারেজ
সূত্র

আপনার সত্যই আপনার এসসিএম এর দোষ / টিকা / সময় বিভক্ত বৈশিষ্ট্যটি শিখতে হবে। কোনও ফাইলের প্রতিটি লাইনের জন্য, এটি দেখায় যে লাইনটি সর্বশেষে পরিবর্তন করা হয়েছিল which দীর্ঘ ইতিহাসের মাধ্যমে অনুসন্ধান করার দরকার নেই।

— কার্ল বিলেফেল্ড

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

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

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

— কার্ক ব্রডহর্স্ট

আমি আপনার সহকর্মীর সাথে 100% সম্মতি

— জানাই

উত্তর:

সাধারাওন বক্তব্য

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

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

যুক্তি দিয়ে যাচ্ছি:

আমি রক্ষণাবেক্ষণের কারণে বলছি, কখন এবং কারা পরিবর্তন করেছে তা জানা গুরুত্বপূর্ণ (এমনকি এই তথ্যটি এসসিএম-এ রয়েছে)।

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

কোডটির কারণেই জীবন রয়েছে life

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

কারণ পরিবর্তনের তারিখ ব্যতীত এসসিএম সরঞ্জামটি না খোলা এবং দীর্ঘ বস্তুর ইতিহাস অনুসন্ধান না করে কখন পরিবর্তনটি চালু হয়েছিল তা জানা অসম্ভব।

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

লেখক যেহেতু গুরুত্বপূর্ণ, লেখকের পরিবর্তনের চেয়ে লেখকের পরিবর্তন আরও বিশ্বাসযোগ্য

সমস্ত লেখক (নিজেকে বাদ দিয়ে) সমানভাবে বিশ্বাসযোগ্য।

তত্পরতার কারণ, এসসিএম সরঞ্জামটি নেভিগেট করার দরকার নেই

যদি আপনার উত্স নিয়ন্ত্রণ সরঞ্জামটি ভারী হয় তবে আপনি এটিকে ভুলভাবে ব্যবহার করছেন বা (সম্ভবত এটি সম্ভবত) আপনি উত্স নিয়ন্ত্রণ ব্যবস্থা অ্যাক্সেস করার জন্য ভুল সেট সরঞ্জাম ব্যবহার করছেন।

লোকেরা 15 বছর আগে কেউ এমন কিছু করার পরিবর্তনে ভয় পাবে, যা পুনরায় গ্রহণযোগ্যভাবে তৈরি করা হয়েছিল ...

কোড যদি 15 বছর স্থায়ী হয় তবে এটি আরও শক্ত হওয়ার সম্ভাবনা বেশি তবে কোডটি যা পর্যালোচনার প্রয়োজন ছাড়াই কেবল 6 মাস স্থায়ী হয়েছে। স্থিতিশীল কোড স্থিতিশীল থাকার প্রবণতা রাখে, বগি কোড সময়ের সাথে আরও জটিল হয়ে যায় (কারণ এটি বগি কারণ সমস্যাটি প্রথম চিন্তার মতো সহজ নয়)।

তথ্যের জন্য উত্স নিয়ন্ত্রণ ব্যবহারের আরও বেশি কারণ।

ইতিহাস এসসিএম-এ রয়েছে

হ্যাঁ. এখনও সেরা কারণ।

বিকাশকারীদের অবশ্যই কোডে সরাসরি ইতিহাসের ইতিহাস সম্পর্কে অবগত থাকতে হবে না

আমার যদি সত্যিই এই তথ্যের প্রয়োজন হয় তবে আমি এটি উত্স নিয়ন্ত্রণে সন্ধান করব।
অন্যথায় এটি প্রাসঙ্গিক নয়।

এই প্যাকেজগুলি বোঝার জন্য প্যাকেজগুলি 15k লাইন দীর্ঘ এবং কাঠামোগত মন্তব্য পেয়েছে

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

— মার্টিন ইয়র্ক
সূত্র

আপনার প্রতিক্রিয়াটির জন্য ধন্যবাদ, আমার দৃষ্টিভঙ্গিটি পরিবর্তন করার জন্য যথেষ্ট যুক্তি রয়েছে :)

— ডিয়েগো আলভারেজ

+1 টি। কেবল একটি সংযোজন: পাঠ্য সম্পাদক (বা ভুল টাইপ, বা ল্যাপস, বা যাই হোক না কেন) এর চেয়ে সোর্স নিয়ন্ত্রণে মিথ্যা বলা অনেক কঠিন।

— tmadmers

যদি আমরা বলি যে মাত্র আট মাস আগে আমরা পিএলএসকিএল-এর জন্য এসসিএম সরঞ্জামগুলি ব্যবহার শুরু করেছি, এবং কোডটিতে 20 বছর রয়েছে, আপনি কী ভাবেন যে আমরা যদি এসসিএম-তে নেই এমন পরিবর্তনের historicতিহাসিক মন্তব্য থেকে লেখক এবং তারিখ সরিয়ে দিই? এটা কোন ধারণা আছে? বা এই মুহুর্তে কোনও ধারণা তৈরি হয় না 15-15 বছর আগে কে এবং কখন পরিবর্তন হয়েছিল? আপনার সময় এবং প্রতিক্রিয়া জন্য tks।

— দিয়েগো আলভেরেজ

আমি আপনার সহকর্মীকে দৃ strongly়ভাবে সমর্থন করি। আপনি যদি কোনও মন্তব্যে পুরানো কোড না রাখেন তবে কেন কিছু পরিবর্তন করা হয়েছে তা যদি আপনি বুঝতে চান তবে আপনি এসসিএমটির দিকে না তাকিয়েই পাবেন না।

টন কমেন্ট না লিখে কোডটি যদি বোঝা যায় না তবে কোডটি টন কমেন্ট ছাড়াই পাঠ্যযোগ্য / রক্ষণাবেক্ষণযোগ্য করে তোলার জন্য আপনার জ্বালানি বিনিয়োগের পরামর্শ দেব।

সর্বোপরি, আপনি প্রোগ্রামারদের ভাড়া রাখেন, গল্পের গল্পকারদের নয় ;-)

— অ্যাক্সেল
সূত্র