"আমি", "আমরা", বা কোড নথিতে নেই

Question

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

The reason we are doing this is...

"আমি" এর পরিবর্তে আমি "আমরা" ব্যবহার করার কারণ হ'ল আমি প্রচুর একাডেমিক লেখা করি যেখানে "আমরা" প্রায়শই পছন্দ হয়।

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

1. "আমরা" ব্যবহার করুন: যে কারণে আমরা এটি করছি ...
2. "আমি" ব্যবহার করুন: যে কারণে আমি এটি করছি ...
3. আমার নাম ব্যবহার করুন: এর কারণটি [my name]হ'ল ...
4. প্যাসিভ ভয়েস: এটি করার কারণটি হ'ল ...
5. না: এটি কর কারণ কারণ ...

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

Comments

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

— কন্ডিশন

# 5 সম্পর্কে কীভাবে: "যখন মানব ইভেন্টের পথে ...";)

— ওয়াক্সউইং

"চার স্কোর এবং সাত সেকেন্ড আগে আমাদের পিতৃপুরুষরা শিখেছিলেন যে ফু'কে বাধা দিতে হবে কমপক্ষে আমাদের বাহিনীকে NUL দিয়ে কাটিয়ে উঠতে হবে"

— ফিলিপ

ইংরাজির উপর দৃ on়ভাবে সম্পর্কিত SE এসই: প্রোগ্রামাররা যখন সত্যই তাদের "আমি" বা 'আপনি' বোঝায় তখন কেন আমরা সর্বদা 'আমরা' ব্যবহার করি? (যা দুর্ভাগ্যক্রমে বন্ধ ছিল)

— ইজকাটা

কেন বলছেন না This code was written like this because...? (প্যাসিভ ভয়েস)

— অ্যালভিন ওয়াং

Answer 1

আমি সাথে যেতে হবে:

# 6। ঘোষিত: ...

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

Comments

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

— জিনাত

@gnat "এটি করার কারণ" ব্যাখ্যায় কিছু যুক্ত করে না। মন্তব্যগুলিতে পয়েন্টটি পাওয়ার জন্য পর্যাপ্ত পাঠ্য থাকা উচিত এবং আরও কিছু নয়। চমত্কার জিনিস, উপস্থাপিকা এবং অন্যান্য ফিলার পাঠ্য ছেড়ে দিন।

— ডেভিড হার্কনেস

@ গ্যাनेट - আমি যখন আপনার মন্তব্য দেখেছি তখন আমি আরও যুক্ত করা শেষ করেছি।

— ববসন

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

— অ্যালান টুরিং

আমি বেশিরভাগ ক্ষেত্রে //যেমন পড়েছি because।

— ইলমো ইউরো

Answer 2

আমি উভয়ই পছন্দ করি না, এবং প্রকৃতপক্ষে সেই সূচনা বাক্যটি পুরোপুরি ছেড়ে দেব এবং কেবল পয়েন্টে পৌঁছব। আমি কেবল "এটি" বলা এড়াতে চেষ্টা করি কারণ মন্তব্যটি কোডের সাথে সিঙ্কে রয়েছে কিনা তা বলার উপায় নেই। পরিবর্তে অন্য কথায়:

// The reason this was done is to prevent null pointer exceptions later on.

আমি বলব:

// Frobnicate the widget first so foo can never be null.

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

Answer 3

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

এখানে একটি নমুনা যা আমি মনে করি পয়েন্টটি চিত্রিত করে।

/// <summary>
/// Takes data from the remote client and stores it in the database.
/// </summary>
/// <param name="data">The data to store.</param>
public void StoreData(ComplexObject data)
{
    // Don't take candy from strangers
    ComplexObject safeData = SanitizeData(data);
    ...
}

Comments

পার্শ্ব নোট: SanitizeDataফিরে আসা উচিত SafeComplexObject। ;)

— জন পুর্ডি

আমি সম্মত, তবে আমি আক্ষরিক (রূপক পরিবর্তে) মন্তব্যগুলি পছন্দ করি, বিশেষত যদি বিভিন্ন ভাষার ব্যাকগ্রাউন্ডের বিকাশকারী হতে পারে।

— জন বি লাম্বে

Answer 4

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

1. কোডটি পরিবর্তন করা হলে মন্তব্যগুলি সর্বদা পরিবর্তন হয় না যা পরে বিভ্রান্তির কারণ হতে পারে।

2. ইউনিট পরীক্ষাগুলি রক্ষণাবেক্ষণকারীকে কোড সহ খেলতে একটি সহজ উপায় দেয়। নতুন কোডবেস শেখা অনেক সহজ হতে পারে যদি আপনার স্বতন্ত্র ইউনিট থাকে তবে আপনি কী পরিবর্তনগুলি পর্যবেক্ষণ করতে পারেন break

যদিও এই অ্যাভিনিউতে আরও বেশি কাজ করা দরকার, ইউনিট টেস্টিং ডকুমেন্টেশনের একটি দুর্দান্ত ফর্ম হতে পারে।

Answer 5

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

আমি কাউকে তাদের কোড মন্তব্য করতে নিরুৎসাহিত করতে পছন্দ করব কারণ তারা কেস, উত্তেজনা এবং তাদের সর্বনামের ব্যক্তি সম্পর্কে উদ্বিগ্ন।

Comments

আমাকে স্পষ্ট করতে দাও: যে মন্তব্যগুলির জন্য আনুষ্ঠানিক ডকুমেন্টেশনের অংশ হয়ে উঠবে, তার জন্য আরও একটি আনুষ্ঠানিক স্বর যথাযথ এবং "আমি" এবং "আমরা" সেরা এড়ানো হ'ল। এই উত্তরের সাথে আমি যা মনে রেখেছিলাম তা ছিল মাঝে মাঝে ব্যাখ্যামূলক মন্তব্য, উদাহরণস্বরূপ আপনি যখন এমন কিছু করেছেন যখন পরের লোকটির কাছে ভুল দেখাবে। সেসব ক্ষেত্রে, যেখানে শুধুমাত্র যারা একই কোড বেস কাজ কি কখনো তা দেখতে হবে, আমি যাই হোক না কেন আপনার সবচেয়ে পরিষ্কারভাবে অর্থ বহন করবেন বলে, এমনকি এটি এটা I wrote the code this way because...বা what we really need here is...। ইন ঐ ক্ষেত্রে, একটি স্পষ্ট মন্তব্য একটি কঠোর শৈলীর চেয়ে আরো গুরুত্বপূর্ণ।

— জন এম গ্যান্ট

Answer 6

"আমি" এর পরিবর্তে আমি "আমরা" ব্যবহার করার কারণ হ'ল আমি প্রচুর একাডেমিক লেখা করি যেখানে "আমরা" প্রায়শই পছন্দ হয়।

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

আপনার নির্দিষ্ট প্রশ্নের হিসাবে: আমি এ জাতীয় মন্তব্যটি ছাড়ব না, যতক্ষণ না এটি শুরু হয়:

// TODO: clean this up, ...

বা যদি না এটি খুব গুরুত্বপূর্ণ কিছু ব্যাখ্যা করে তবে তা কোড থেকে এতটা পরিষ্কার নাও হতে পারে। সেক্ষেত্রে কমেন্টটি যতটা সম্ভব সংক্ষিপ্ত করে দিন।