26

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

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

ঠিক আছে, আমি শুরু করব।

সাধারণত, আমার /* */যখন অনেকগুলি লাইনে মন্তব্য করার প্রয়োজন হয় তখনও আমি মন্তব্যগুলি ব্যবহার করি না ।

সুবিধাগুলি : আপনি যখন এক লাইনের মন্তব্যের সাথে এই জাতীয় বাক্য গঠনটি মিশ্রিত করেন তখন কোডটি দৃশ্যত আরও ভাল দেখায়। বেশিরভাগ আইডিই'র নির্বাচিত পাঠ্য মন্তব্য করার ক্ষমতা থাকে এবং তারা সাধারণত এটি এক-লাইন সিনট্যাক্স দিয়ে করেন।

অসুবিধাগুলি : আইডিই ছাড়াই এই জাতীয় কোড সম্পাদনা করা শক্ত।
যে কোনও সমাপ্ত মন্তব্যের শেষে "বিন্দু" রাখুন।

উদাহরণ স্বরূপ:
```
//Recognize wallpaper style. Here I wanted to add additional details
int style = int.Parse(styleValue);
//Apply style to image.
Apply(style);
```
সুবিধা : কেবলমাত্র আপনার সমাপ্ত মন্তব্যগুলিতে "বিন্দু" রাখুন। কখনও কখনও আপনি অস্থায়ী তথ্য লিখতে পারেন, সুতরাং "ডট" এর অভাব আপনাকে বলবে যে আপনি এই মন্তব্যটিতে ফিরে এসে কিছু অতিরিক্ত পাঠ্য যুক্ত করতে চেয়েছিলেন।
গণনাগুলিতে পাঠ্য সারিবদ্ধ করুন, প্যারামিটারগুলি মন্তব্য করুন ইত্যাদি

উদাহরণ স্বরূপ:
```
public enum WallpaperStyle
{
    Fill = 100,     //WallpaperStyle = "10"; TileWallpaper = "0".
    SizeToFit = 60, //WallpaperStyle = "6";  TileWallpaper = "0".
    Stretch = 20,   //WallpaperStyle = "2";  TileWallpaper = "0".
    Tile = 1,       //WallpaperStyle = "0";  TileWallpaper = "1".
    Center = 0      //WallpaperStyle = "0";  TileWallpaper = "0".
};
```
সুবিধাগুলি : আপনার যা প্রয়োজন তা সন্ধান করার জন্য আরও ভাল এবং দৃশ্যমান আরও সহজ দেখায়।

অসুবিধাগুলি : সারিবদ্ধ করার জন্য সময় ব্যয় করা এবং সম্পাদনা করা আরও শক্ত।
মন্তব্যে এমন পাঠ্য লিখুন যা আপনি কোড বিশ্লেষণ করে অর্জন করতে পারবেন না।

উদাহরণস্বরূপ, বোকা মন্তব্য:
```
//Apply style.
Apply(style);
```
সুবিধা : আপনার মন্তব্যগুলিতে কেবল দরকারী তথ্য সহ পরিষ্কার এবং ছোট কোড থাকবে have

coding-style comments

— ক্যারিলো এম
সূত্র

2

ভিমে মন্তব্যগুলি সারিবদ্ধ করুন: Align.vim ব্যবহার করুন এবং :3,7 Align //3-7 লাইনে মন্তব্যগুলি সারিবদ্ধ করতে করুন।

— বেনোইট

3

"হার্ড সম্পাদনায় যান আইডিই ছাড়া" - ভাল, আপনি কি করবেন যে ঘন ঘন?

3

আমি মনে করি যে কোনও ভাষা / পরিবেশের পছন্দটি প্রশ্নটিতে লক্ষ্য করা উচিত। কারও কারও কাছে বিদ্যমান গাইডলাইন রয়েছে ( .NET- এর বেশিরভাগ স্ট্যান্ডার্ড এক্সএমএল মন্তব্য রয়েছে: এমএসডিএন.মিকোসফটওয়্যার /en-us/library/b2s063f7.aspx )।

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

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

— ব্যবহারকারী অজানা

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

— মশা

16

নীচে কিছু বিবৃতি বেশ ব্যক্তিগত, যদিও কিছু ন্যায্যতা সহ, এবং এই উপায় হতে বোঝানো হয়।

মন্তব্য প্রকার

সংক্ষিপ্ত সংস্করণের জন্য ... আমি এর জন্য মন্তব্যগুলি ব্যবহার করি:

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

বিশদ এবং (সম্ভবত অস্পষ্ট) কারণে নীচে পড়ুন।

পিছনে মন্তব্য

ভাষার উপর নির্ভর করে হয় সিঙ্গল-লাইনের মন্তব্য বা মাল্টি-লাইন মন্তব্য ব্যবহার করে। এটি নির্ভর করে কেন? এটি কেবল একটি মানীকরণের বিষয়। আমি যখন সি কোডটি লিখি, আমি পূর্বনির্ধারিত এএনএসআই সি 89 কোডটি ডিফল্টরূপে পছন্দ করি, তাই আমি সর্বদা থাকতে পছন্দ করি /* comments */।

তাই আমার বেশিরভাগ সময় সিতে এটি থাকত এবং কখনও কখনও সি-জাতীয় সিনট্যাক্স সহ ভাষার জন্য (কোডবেজের স্টাইলের উপর নির্ভর করে):

typedef struct STRUCT_NAME {
  int fieldA;                /* aligned trailing comment */
  int fieldBWithLongerName;  /* aligned trailing comment */
} TYPE_NAME;

ইমাকস দুর্দান্ত এবং আমার সাথে এটি করে M-;।

ভাষাটি যদি একক-লাইন মন্তব্যগুলিকে সমর্থন করে এবং সি-ভিত্তিক না হয়, তবে আমি একক-লাইন মন্তব্যগুলি ব্যবহার করতে আরও linedকৃত হব। অন্যথায়, আমি এখন অভ্যাসটি গ্রহণ করেছি ভয়ে ভীত। যা অগত্যা খারাপ নয়, কারণ এটি আমাকে সংক্ষিপ্ত হতে বাধ্য করে।

মাল্টি-লাইন মন্তব্য

আমি এর জন্য একক-লাইন মন্তব্যগুলি ব্যবহার করা আপনার ধারণার সাথে দ্বিমত পোষণ করছি আরও দৃষ্টি আকর্ষণীয়। আমি এটি ব্যবহার:

/*
 * this is a multi-line comment, which needs to be used
 * for explanations, and preferably be OUTSIDE the a
 * function's or class' and provide information to developers
 * that would not belong to a generated API documentation.
 */

বা এটি (তবে আমি ব্যক্তিগত ঘন ঘন কপিরাইট বিজ্ঞপ্তি বা বেশিরভাগ কপিরাইট বিজ্ঞপ্তি ব্যতীত আর কখনও তা করি না - এটি আমার জন্য historicalতিহাসিক এবং আমার শিক্ষাগত পটভূমি থেকে আসে Unfortunately দুর্ভাগ্যক্রমে, বেশিরভাগ আইডিই অটো-ফর্ম্যাট ব্যবহার করার সময় এটিকে ঘৃণা করে) :

/*
** this is another multi-line comment, which needs to be used
** for explanations, and preferably be OUTSIDE the a
** function's or class' and provide information to developers
** that would not belong to a generated API documentation.
*/

যদি সত্যিই প্রয়োজন হয়, তবে আমি অনুগ্রহপূর্বক মন্তব্যের জন্য আমি পূর্বে যা উল্লেখ করেছি তা ব্যবহার করে ইনলাইন মন্তব্য করব, যদি এটি অনুমানযোগ্য অবস্থানে ব্যবহার করা বোধগম্য হয়। খুব বিশেষ প্রত্যাবর্তন ক্ষেত্রে উপর, উদাহরণস্বরূপ, বা নথির একটি থেকে switchএর caseবিবৃতি (বিরল, আমি ব্যবহারের প্রায়ই সুইচ করবেন না), অথবা যখন আমি একটি শাখা নথি if ... elseনিয়ন্ত্রণ প্রবাহ। যদি এটিগুলির মধ্যে একটি না হয় তবে সাধারণত ফাংশন / পদ্ধতি / ব্লকের ধাপগুলি রূপরেখার বাইরে স্কোপের বাইরে একটি মন্তব্য ব্লক আমার কাছে আরও অর্থবোধ করে।

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

try {
  /* you'd have real code here, not this comment */
} catch (AwaitedException e) {
  /*
   * Nothing to do here. We default to a previously set value.
   */
}

যা আমার জন্য ইতিমধ্যে কুরুচিপূর্ণ তবে আমি কিছু পরিস্থিতিতে সহ্য করব।

ডকুমেন্টেশন মন্তব্য

জাভাদোক এবং আল।

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

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

মন্তব্য-আউট কোড

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

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

মন্তব্য শৈলী

আমি সাধারণত লেখার ঝোঁক:

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

লিটারেট প্রোগ্রামিং সম্পর্কিত একটি নোট

ডোনাল্ড নুথের এই কাগজে প্রবর্তিত হিসাবে আপনি লিটারেট প্রোগ্রামিংয়ে আগ্রহী হতে চাইতে পারেন ।

সাক্ষরতার প্রোগ্রামিং দৃষ্টান্ত, [...] কম্পিউটারের দ্বারা আরোপিত পদ্ধতি এবং ক্রম অনুযায়ী প্রোগ্রামগুলি লেখার থেকে দূরে সরে যাওয়ার প্রতিনিধিত্ব করে এবং এর পরিবর্তে প্রোগ্রামারদের তাদের যুক্তি ও প্রবণতার দ্বারা দাবি করা ক্রমে প্রোগ্রামগুলি বিকাশ করতে সক্ষম করে। 2 সাহিত্যের প্রোগ্রামগুলি একটি সাধারণ মানুষের ভাষায় যুক্তিগুলির নিরবচ্ছিন্ন প্রকাশ হিসাবে লেখা হয়, অনেকটা প্রবন্ধের পাঠ্যের মতো [...]।

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

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

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

— haylem
সূত্র

ডকুমেন্টেশন মন্তব্য থেকে মন্তব্য-আউট কোড পার্থক্য জন্য +1। আমি তাদের নীচে শিকার করা ঘৃণা করি: পি

— ডেল্ট্রেম

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

— haylem

ক্রিয়াকলাপ বা টাস্ক ট্যাগের মন্তব্যে এই উত্তরটি দেখুন ।

— হাইলেম

14

আমি যখন বিশ্ববিদ্যালয়ে যাই তখন আমাকে সর্বদা কোডের প্রতিটি লাইন এবং প্রতিটি পদ্ধতি শিরোনামে মন্তব্য করতে শেখানো হয়েছিল। এটি এমনভাবে drোল। করা হয়েছিল যে আপনি প্রশ্ন ছাড়াই এটি করেছেন। বিভিন্ন সংস্থায় বেশ কয়েকটি চটপটি উন্নয়ন দলের অংশ হওয়াতে আমি বলতে পারি যে নীল চাঁদে আমি একবার মন্তব্য লিখতে পারি।

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

public void Login(string username, string password)
{
    // Get the user entity
    var user = userRepository.GetUser(username);


    // Check that the user exists
    if (user == null)
    {
        throw new UserNotFoundException();
    }

    // Check that the users password matched
    if (user.HashedPassword != GetPasswordHash(password))
    {
        throw new InvalidUsernamePasswordException();
    }

    //Check that the users account has not expired
    if (user.Expired)
    {
        throw new UserExpiredException();
    }

    //Mark user as logged in
    ...
}

এটি এমন কিছুতে আবার লিখিত হতে পারে যা আরও বেশি পঠনযোগ্য এবং সম্ভবত পুনরায় ব্যবহারযোগ্য:

public void Login(string username, string password)
{
    var user = GetUserForUsername(username);

    CheckUsersPasswordMatched(user, password);

    CheckUserAccountNotExpired(user);

    MarkUserAsLoggedIn(user);
}

private void User GetUserForUsername(string username)
{
    var user = userRepository.GetUser(username);

    if (user == null)
    {
        throw new UserNotFoundException();
    }
    return user;
}

private void CheckUsersPasswordMatched(User user, string password)
{
    if (user.HashedPassword != GetPasswordHash(password))
    {
        throw new InvalidUsernamePasswordException();
    }
}

private void CheckUserAccountNotExpired(User user)
{
    if (user.Expired)
    {
        throw new UserExpiredException();
    }
}

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

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

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

— Bronumski
সূত্র

2

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

— কেভিন

2

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

— jeremy.mooer

5

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

//Apply style.

Apply(style);

হতে হবে

// Unlike the others, this image needs to be drawn in the user-requested style apply(style);

আমাদের বেশিরভাগই বিদ্যমান কোডগুলিতে দলগুলিতে কাজ করেন, বাকি টিমগুলি যেভাবে ইতিমধ্যে সম্পন্ন হচ্ছে সেভাবে ফর্ম্যাট করে। সুন্দরের চেয়ে অনেক বেশি গুরুত্বপূর্ণ ধারাবাহিকতা।

— mattnz
সূত্র

এই উদাহরণটি কী তা আরও মনোযোগ সহকারে পড়ুন। আমি ইতিমধ্যে এটি উল্লেখ করেছি: "উদাহরণস্বরূপ, মূ .় মন্তব্য:"।

— কিরিলো এম

1

তোমার যুক্তিটা বুঝেছি. আমি নিশ্চিত যে সত্যিকারের কোডটিতে আমি কত "বোকামি মন্তব্য" দেখেছি তা অবাক করে দেখবেন না, তাই আমি আমার পোস্টের পাশে দাঁড়িয়ে আছি। বিন্যাসে কিছু আসে যায় না, বিষয়বস্তু করে।

— mattnz

3

যতটা সম্ভব, আপনার কোডটি এমনভাবে লিখুন যাতে মন্তব্যগুলি সম্পূর্ণ বহিরাগত হবে। যখন কোডটি এমনভাবে লেখা না যায় তখন কেবল মন্তব্য যুক্ত করুন যাতে এটি একটি গুরুত্বপূর্ণ ধারণাটি সুস্পষ্ট হয়ে যায়।

— ডেভ
সূত্র

2

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

— ক্যারিলো এম
সূত্র

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

— অ্যাডাম বাইরটেক

2

আমি প্রায়শই এর মতো মন্তব্য দেখতে পাই এবং কিছু সরঞ্জাম স্বয়ংক্রিয়ভাবে সেভাবে উত্পন্ন করে:

/** 
 * This is an example, how to waste vertical space,
 * and how to use useless asterixes.
 */

দুটি লাইন কম:

/** This is an example, how to spare vertical space,
    and how to avoid useless asterixes. */

আইডিই এবং সম্পাদকগণ, নোটপ্যাড-স্তরের সামান্য উপরে, মন্তব্যগুলি সনাক্ত করতে এবং এগুলিকে আলাদা রঙে মুদ্রণ করতে সক্ষম। অ্যাসেরিক্সগুলি দিয়ে লাইনের শুরুটি সাজানোর দরকার নেই।

এমনকি আপনি কিছু বাইট ছাড়েন, যদি আপনি ইনডেন্টেশনের জন্য কোনও ট্যাব ব্যবহার করেন।

আপনি যদি একটি পরিশীলিত সম্পাদক ব্যবহার না করেন, যা ধূসর সুরে মন্তব্যটি সরবরাহ করে, বৃহত পরিমাণে গ্রহাণু একটি জোর হিসাবে কাজ করবে এবং আপনার মনোযোগ আকর্ষণ করবে, যা করার সঠিক জিনিসটির বিপরীত: পিছনে থাকতে হবে।

— অজানা ব্যবহারকারী
সূত্র

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

— হাইলেম

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

— হাইলেম

আমি আমার সময় ভাঁজ এবং কোডটি প্রকাশ করতে ব্যয় করতে পছন্দ করি না। আমি আপনার পণ্য-যুক্তিতে সম্মতি জানাব, যদি বাইটগুলির একক সুবিধা হয় তবে তারা তা করে না। যদি আপনার সম্পাদকের কোড হাইলাইটিং না থাকে তবে যান, নিজেকে একটি কমোডোর 64 কিনুন। :) ইনডেন্টেশন আর্গুমেন্টটি ধরে রাখে না, কারণ যদি ইনডেন্টেশনটি মন্তব্য থেকে মন্তব্যকে পৃথক করে, এটি কোডটিও মন্তব্য থেকে আলাদা করে দেয়। মন্তব্য করা কোডের একটি বৃহত্তর অংশটি দেখুন - একটি অ্যাসেরিক্সের ব্লক একটি জোর হিসাবে কাজ করে।

— ব্যবহারকারী অচেনা

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

— হাইলেম

হ্যাঁ, আমি এগুলি ব্লক করতে শিখেছি - প্লাগইন সহ, যা বিজ্ঞাপন ব্লকার বলে called Eclipse এর একটি ভাঁজ ফাংশন রয়েছে, তবে gedit, যা আমি ছোট, একক ফাইল প্রোগ্রামগুলির জন্য ব্যবহার করি, তা হয়নি।

— ব্যবহারকারী অজানা

2

আমার কাজের কোড জুড়ে আমি এখানে একটি "অ্যান্টি-প্যাটার্ন" পেয়েছি: "পরিবর্তনের লগ" হিসাবে মন্তব্যগুলির ব্যবহার; আপনার সংস্করণ নিয়ন্ত্রণ সিস্টেমে লগই এর জন্য। কোডটি এই জাতীয় জিনিসগুলির সাথে ছড়িয়ে পড়ে:

// 05-24-2011 (John Doe): Changed this method to use Foo class instead of Bar

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

// (John Doe) 05-24-2011 not sure why we are using this object?
FooBar oFooBar = Quux.GetFooBar(iFooBarID, bSomeBool);
oFooBar.DiscombobulateBaz();

// (John Doe). This method is poorly named, it's used for more 
// than just frazzling arvadents
public int FrazzleArvadent(int iArvadentID)

— ওয়েইন মোলিনা
সূত্র

2

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

— ক্যারিলো এম
সূত্র

1

কোড পাঠকরা সাধারণত তিনটি প্রশ্নের উত্তর দেওয়ার চেষ্টা করছেন:

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

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

যদি আমি "ডাবল দৈর্ঘ্য" দেখি আমি জিজ্ঞাসা করব "পরিমাপের একক কী?" একটি মন্তব্য যোগ করবেন না। পরিবর্তনশীল নাম পরিবর্তন করুন। যদি আমি কোডের একটি ব্লক দেখতে পাই এবং আমি বলি "এটি কী করে?", কোনও মন্তব্য যুক্ত করবেন না। একটি অর্থবহ নাম সহ একটি ফাংশন নিষ্কাশন করুন। যদি আপনি কোনও ফাংশন নিষ্কাশন করতে না পারেন কারণ এটির জন্য 17 টি আর্গুমেন্ট দরকার হয়, তবে কোডটি রিফ্যাক্টর করুন।

— কেভিন ক্লাইন
সূত্র

শৈলী এবং মন্তব্য কোডের সুপারিশ

মন্তব্য প্রকার

পিছনে মন্তব্য

মাল্টি-লাইন মন্তব্য

ডকুমেন্টেশন মন্তব্য

মন্তব্য-আউট কোড

মন্তব্য শৈলী

লিটারেট প্রোগ্রামিং সম্পর্কিত একটি নোট