কীভাবে বা কী পরিবর্তে কেন আপনাকে মন্তব্য করার উদাহরণ রয়েছে? [বন্ধ]

Question

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

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

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

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

Comments

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

— ড্যান পিচেলম্যান

There are many questions on whether comments are good or bad, but no one that addresses the specific question of what are good examples of comments that tell you WHY. প্রত্যেকে যদি একটি বৈধ উদাহরণ দেয় তবে সেগুলি সমস্ত সঠিক উত্তর। এই ওয়েবসাইটটির ফর্ম্যাট এমন একটি প্রশ্নোত্তর প্রক্রিয়া সহজলভ্য করা যেখানে সমস্ত উত্তর সমানভাবে তৈরি হয় না।

— ডেভিড ক্যাসিনস্কি

শুভ পয়েন্ট, @ ডেভিড-ক্যাকিজেনস্কি। আপনি কি পরামর্শ দিচ্ছেন?

— রিক

আমার মাথার শীর্ষে, আমি প্রশ্নের বাক্যাংশের কোনও উপায় ভাবতে পারি না যাতে একটি উদাহরণ বা সাধারণীকরণ কৌশলটি "সেরা" উত্তর হতে পারে। পি.এস. এর একটি চ্যাটের অংশ রয়েছে: chat.stackexchange.com/rooms/21/the- হোয়াইটবোর্ড , তবে সম্ভবত আপনার প্রশ্নের জন্য এটির চেয়ে আরও ভাল ফোরাম হতে পারে। সমস্ত ন্যায়বিচারে, দেখে মনে হচ্ছে আপনার প্রশ্নটি এখানে সম্প্রদায়ের কাছ থেকে ইতিবাচক প্রতিক্রিয়া পাচ্ছে, তাই এটি উদ্বিগ্ন হওয়ার মতো নয়। দরকারী মন্তব্যের উদাহরণ সন্ধানের জন্য আমি যে সেরা পরামর্শ দিতে পারি তা হ'ল জনপ্রিয় পাবলিক গিট রিপোজিটরিগুলি ব্রাউজ করা।

— ডেভিড ক্যাসিনস্কি

Answer 1

সর্বাধিক সাধারণ এবং সবচেয়ে স্বতন্ত্র উদাহরণ হ'ল বিভিন্ন কর্মক্ষেত্রের চারপাশের মন্তব্য comments উদাহরণস্বরূপ এটি একটি:

https://github.com/git/git/blob/master/compat/fopen.c :

/*
 *  The order of the following two lines is important.
 *
 *  FREAD_READS_DIRECTORIES is undefined before including git-compat-util.h
 *  to avoid the redefinition of fopen within git-compat-util.h. This is
 *  necessary since fopen is a macro on some platforms which may be set
 *  based on compiler options. For example, on AIX fopen is set to fopen64
 *  when _LARGE_FILES is defined. The previous technique of merely undefining
 *  fopen after including git-compat-util.h is inadequate in this case.
 */
#undef FREAD_READS_DIRECTORIES
#include "../git-compat-util.h"

আপনি নিশ্চয়ই গিট এবং লিনাক্স উত্সগুলিতে আরও উদাহরণ পাবেন; উভয় প্রকল্পই এই নিয়মটি অনুসরণ করার চেষ্টা করে।

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

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

1. সমস্ত জমা দেওয়া পরিবর্তনগুলি পর্যালোচনা করা হয় এবং কমিট লগটি পর্যালোচনাকারীকে পরিবর্তনের ব্যাখ্যা দিতে হয়।
2. কোনও ত্রুটি পাওয়া গেলে, পূর্বের ভুল আচরণে ফিরে এড়াতে "পিক্যাক্স" বা "দোষ" ব্যবহার করে সংশ্লিষ্ট লগগুলি পুনরুদ্ধার করা হয়।

(দ্রষ্টব্য: এই দুটি উদাহরণ সহ গিট রেপোতে আমার প্রায় 10 মিনিটের এলোমেলো ব্রাউজিং লেগেছিল, সুতরাং সেখানে আরও সন্ধান করা নিশ্চিত হবে)

Answer 2

একটি মন্তব্য যা আপনাকে কোডের পিছনে যুক্তি কেন ব্যাখ্যা করে তা বলে tells উদাহরণস্বরূপ:

// We need to sync the values if the temp <doodad> GUID matches one of the active <doodad>'s
// GUID, as the temp <doodad> has the most recent values according to the server and said 
// values might have changed since we added the <doodad>. We want a user to be able to <foo> 
// the <doodad> whenever, which means those values must be accurate.
for (doodad in doodads) {
    if ([doodad guid] == [tempDoodad guid]) {
        [doodad updateFromDoodad:tempDoodad];
        break;
    }
}

একটি মন্তব্য যা আপনাকে জানায় যে কোড কী করে তা কীভাবে ব্যাখ্যা করে।

// Loop through our <doodads> and check for a GUID match. If it matches, copy the new values
// on the <doodad> that matches 
for (doodad in doodads) {
    if ([doodad guid] == [tempDoodad guid]) {
        [doodad updateFromDoodad:tempDoodad];
        break;
    }
}

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

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

/*
 We're going to do something really hacky here and use a custom partial
 implementation of traceroute to get our gateway IP address.

 [rant removed - irrelevant to the point]

 There's no good way to get at the gateway address of an iDevice
 right now. So, we have two options (per https://devforums.apple.com/message/644915#644915 ):
 1. Get at and parse the routing table (like netstat -rn, or route -n)
 2. Do a traceroute and grab the IP address for the first hop

 As far as I can tell, the former requires <sys/route.h> from the Mac OS X
 header files, which doesn't seem like a good idea to me. Also, there's a
 thread on the Apple Developer forums that seems to imply that header isn't
 in iOS for a reason (https://devforums.apple.com/message/774731#774731 ).

 So when we send our request with a TTL of one it will survive a single hop
 to the router and return, triumphant, with the router's IP address!

 Viva la kludge!

 PS: Original source was the below SO question, but I've modded it since then.
 http://stackoverflow.com/questions/14304581/hops-tracing-ttl-reciveform-on-ios/14304923#14304923
 */

// Default to using Google's DNS address. We used to try checking www.google.com
// if reachability reported we had internet, but that could still hang on routers
// that had no internet connectivity - not sure why.
const char *ip_addr = [kGoogleDNS UTF8String]; // Must be const to avoid undefined behavior
struct sockaddr_in destination,fromAddr;
int recv_sock;
int send_sock;

// ... more code follows

Comments

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

— জানু হুদেক

আপনার প্রতিক্রিয়া অনুসারে @ জানহুদেক অ্যাডজাস্টেড ঠিক আছে?

— thegrinner

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

— ব্রায়ান

Answer 3

আমি জেফ আতউড তার ব্লগ পোস্ট কোডে তৈরি একটি উক্তি দিয়ে আমার উত্তরটি শুরু করতে চাই , আপনাকে কীভাবে, মন্তব্য আপনাকে বলবে কেন :

সেরা ধরণের মন্তব্যগুলি আপনার প্রয়োজন হয় না

তিনি আরও বলেছেন:

ক্রাচের মতো মন্তব্যে নির্ভর না করে আপনার কোডটি যত সহজে সম্ভব বুঝতে সহজতর করার চেষ্টা করা উচিত। কোডটি বুঝতে সহজ হওয়া যায় না এমন পর্যায়ে আপনি মন্তব্যগুলি যুক্ত করা শুরু করা উচিত।

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

উদাহরণস্বরূপ, যদি ডেটা পার্স করার সময় সপ্তাহের দিনের একটি টেবিলটি পূরণ করার জন্য 2 টি ডাইমেনশনাল হ্যাশ টেবিল সহ 3 নেস্টেড লুপগুলি ব্যবহার করা হয়, তবে কয়েক সপ্তাহের জন্য না তাকালে এবং হঠাৎ রিফ্যাক্টরিং না করে যদি কেউ নিজের দ্বারা এমনকি কী করেছিলেন তা ট্র্যাক হারিয়ে ফেলা খুব সহজ।

[loop1]6oclock -> [loop2]Monday -> [loop3]stage 1 to 4
         -> tuesday-> stage 1 to 4
         ...
         -> Saturday -> stage 1 to 4
    7oclock -> Monday-> stage 1 to 4
        ....etc.

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

// added a zero before the actual day in order for the days always to be 2 digits long.
if( actualDayFuture < 10 ) 
{ 
     actualDayFuture = padIfSingleDigitDate(actualDayFuture); 
}

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

অবশ্যই এক্সপি এর কোড রয়েছে যা স্ব ব্যাখ্যা করছে, তবে একটি লাইনের মন্তব্যে কি আঘাত লাগে?

আমি এই ব্লগ থেকে নিম্নলিখিত বিধিগুলি খুব সহায়ক বলে মনে করি:

• লেখার আগে উপাদানটি বুঝতে হবে
• আপনার শ্রোতা চতুর্থ গ্রেডের মতো লিখুন
• পাঠকরা কীভাবে আপনার ভুল ব্যাখ্যা করতে পারে তা ভেবে দেখুন

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

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

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

Comments

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

— ক্রিস চুদমোর

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

— ক্রিস চডমোর

বিজ্ঞাপন "শিওর এক্সপিতে এমন কোড রয়েছে যা স্বতঃ ব্যাখ্যা করা আছে, তবে একটি লাইনের মন্তব্যতে কি আঘাত লাগে?": মন্তব্যগুলি ভাল, তবে অতিরিক্ত মন্তব্য করারও একটি আশঙ্কা রয়েছে। মন্তব্যের প্রতিটি লাইন এমন একটি যা কোড পরিবর্তন করার সময় কেউ আপডেট করতে ভুলে যেতে পারে।

— জানু হুডেক

এটি বলার আরও ভাল উপায় হ'ল "সর্বোত্তম ধরণের মন্তব্যটি কোনও মন্তব্যের প্রয়োজনের অনুপস্থিতি"। যে মন্তব্যগুলি প্রয়োজন হয় না (তবে যেভাবেই লেখা হয়) ভাল মন্তব্য নয়।

— কাজ

আকর্ষণীয় যে উল্লেখযোগ্য কোডটি int directionCode = (x > oldX) ? DIRECTIONCODE_RIGHT : (x > oldX) ? DIRECTIONCODE_LEFT : DIRECTIONCODE_NONE;ত্রুটিযুক্ত in অবশ্যই হওয়া উচিত ... (x < oldX) ? DIRECTIONCODE_LEFT : DIRECTIONCODE_NONE;। ভাল মন্তব্য ধারণা - খারাপ কোড।

— chux

Answer 4

আমি মন্তব্যগুলি হ'ল প্রসঙ্গগুলিতে কোনও নির্দিষ্ট কার্যকারিতা / কোডটি আরও ভালভাবে ব্যাখ্যা করা হয়েছে বা প্রোগ্রামিংয়ের একটি নির্দিষ্ট উপায় কেন বেছে নেওয়া হয়েছে তা ব্যাখ্যা করার প্রবণতাগুলিতে আমি কমিয়ে আছি।

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

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

সুতরাং 'কেন' আপনার পছন্দ অনুসারে একটি যুক্তি দেওয়া উচিত ।

Comments

উল্লেখগুলি একটি দুর্দান্ত উদাহরণ example // এই পদ্ধতিটি ফুবিটকে পুনরায় সংশ্লেষ করতে furshclingeheimer অ্যালগরিদম ব্যবহার করে। দেখুন HTTP: // ...

— ক্রিস চডমোর

Answer 5

মন্তব্য বলা উচিত কি কোড না, অগত্যা দ্বারা deliniated নেই কেন , কীভাবে , অথবা যা । আপনার যদি ভাল নাম থাকে এবং ভালভাবে বর্ণনা করা ফাংশন থাকে তবে কোডটি আপনাকে ঠিক কী ঘটছে তা বলতে পারে quite উদাহরণ স্বরূপ:

List<LightMap> maps = makeLightmaps(receivingModels);
TrianglePartitioner partition = new Octree(castingTriangles);
List<Photon> photons = firePhotons(lights, partition);

if (photons.Count > 0)
{
      PhotonPartitioner photonMap = new KDTree(photons);
      gatherPhotons(maps, photonMap, partition, lights);
}

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

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

double randomA = localGenerator.NextDouble();
double randomB = localGenerator.NextDouble();

//http://mathworld.wolfram.com/SpherePointPicking.html
double theta = 2 * Math.PI * randomA;
double phi = Math.Acos(2 * randomB - 1);

Vector3 randomDirection = new Vector3(Settings.ambientRayLength * (float)(Math.Cos(theta) * Math.Sin(phi)),
                                      Settings.ambientRayLength * (float)(Math.Sin(theta) * Math.Sin(phi)),
                                      Settings.ambientRayLength * (float)Math.Cos(phi));

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

Random random = new Random();
Parallel.For(0, maxPhotons, delegate(int photonIndex, ParallelLoopState state)
{
    ...
    //I don't actually care if this random number is unique between threads, threadsafty is not that big of a deal
    //  in this case and locking the random object could cause a lot of lock contention
    while (random.NextDouble() > reflectProbability)
    {
        ...
    }
    ...
}

প্রথমে সমান্তরাল লুপের ভিতরে কেন এলোমেলো বস্তুটি তৈরি করা হয়নি তা বলা যায়, সম্ভবত এটি উন্নত করা যেতে পারে। যদি কোনও কারণ না থাকে, তবে এটির সাথে কেউ উপস্থিত হতে পারে এবং উপলব্ধি করতে পারে যে পুরো ধারণাটি বোকা এবং রিফ্যাক্টরিংয়ের জন্য একটি ভাল জায়গা।

Comments

মন্তব্যগুলির WriteTextপরিবর্তে মন্তব্যগুলির আগে যখন প্রয়োজন হয় তখন কোডটির কি মন্তব্যগুলির প্রয়োজন হয় না তা বর্ণনা করা কি যুক্তিসঙ্গত //?

আমি উত্তরে বলেছি, মুদ্রণ বিবৃতি না থাকলেও মন্তব্যগুলি বিনা পর্বস্থল, তবে আমি বিষয়টিকে আরও পরিষ্কার করার জন্য মুদ্রণ বিবৃতি মুছে ফেলার জন্য এটি সম্পাদনা করেছি।

— চেভি গম্বল

Answer 6

এটি বিভিন্ন ধরণের "কেন" সনাক্ত করতে সহায়ক হতে পারে - উল্লেখযোগ্য:

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

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

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

Answer 7

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

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

// transform the x,y point location to the nearest hexagonal cell location
ix1 = (int)floor(0.5 + x + y/2);
iy1 = (int)floor(0.5 + y);

তার উপরে, সময়ের সাথে সাথে মডেলগুলি পরিবর্তন হয় এবং সেই পরিবর্তনগুলি কোডে স্থানান্তর করতে হয়। সুতরাং মন্তব্যে কেবল কোডটিতে কিছু "কেন" রয়েছে তা বলা উচিত নয়, তবে প্রত্যাশিত মডেল পরিবর্তনের প্রতিক্রিয়ায় কীভাবে এটি পরিবর্তন করা যায় তা গুরুত্বপূর্ণ । উদাহরণ:

// to change to square cell locations, remove the "+ y/2" in the above code

আমি মনে করি মন্তব্যের জন্য সেই উদ্দেশ্যটি কখনও কখনও অবহেলিত।

Comments

প্রশ্ন উদাহরণ চাইছে। এই উত্তরটিকে আরও কার্যকর করার জন্য আপনি একটি উদাহরণ যুক্ত করতে পারেন?

— ব্রায়ান ওকলি

কোডের প্রথম অংশটি আমার কাছে "কী," ব্যাখ্যা করার ক্লাসিক উদাহরণের মতো দেখায়। এটি একটি খারাপ মন্তব্য নয়, তবে আমি মনে করি না এটি ওপি-র প্রশ্নের উত্তর দেয়।

@ জন: মন্তব্যটি না থাকলে পাঠক কী ঘটছে তা দেখতে পাবেন, তবে কেন তা জানেন না why

— মাইক ডুনলাভে

@ মাইকডুনলাভে: আমি একমত নই আমার এখনও কোনও ধারণা নেই - আপনি কেন নিকটতম ষড়্ভুজীয় ঘরের অবস্থান চান? এই অবস্থানটি পাওয়ার উদ্দেশ্য কী ? আমি এই দুটি লাইন মুছে ফেললে কি এটির কোনও ক্ষতি হবে?

Answer 8

আমার সমস্ত মন্তব্য 'কেন' টাইপের নয়, তবে অনেকগুলি।
এগুলির একটি উদাহরণ (দেলফি) উত্স ফাইল থেকে:

// For easier access to the custom properties:

function GetPrivate: Integer;   // It's an integer field in the external program so let's treat it like that here

// The below properties depend on the ones above or are calculated fields.
// They are kept up-to-date in the OnEventModified event of the TTSynchronizerStorage
// or in the ClientDataSet.OnCalcFields of the TcxDBSchedulerStorage.DataSource.DataSet
property IsModified       : Boolean   read GetIsModified   write SetIsModified;
property IsCatTT          : Boolean   read GetIsCatTT      write SetIsCatTT;
property IsSynced         : Boolean   read GetIsSynced     write SetIsSynced;

lLeftPos := pos(' - [',ASubject); // Were subject and [shiftnaam:act,project,cust] concatenated with a dash?

// Things that were added behing the ] we will append to the subject:

// In the storage the custom value must also be set for:
Self.SetCustomFieldValueByname(cCustFldIsCatTT,Result);

// When we show the custom fields in a grid, the Getters are not executed,
// because the DevEx code does not know about our class helpers.
// So we have two keep both properties synchronized ourselves:

// lNewMasterEvent was set to usUpdated, overwrite because we added:
if ARepair then
  lNewMasterEvent.CustUpdateStatus := usRecreated

// The source occurrence date may have bee changed. Using GetOriginalDate we can retrieve the original date,
// then use that for creating a target occurrence (and update its date):

lNewTTOccurrence.CustSyncEntryID := cSyncEntryID0;    // Backward compatibility with old sync methode

// Single event became recurring or vice versa; replace entire event

// In contradiction to CopySingleEventToTimeTell, CopyMasterEventToTimeTell does not have a ANewStatus parameter
// because master events are always added.

দ্রষ্টব্য যে (আমার) কেন মন্তব্যগুলি সাধারণত কোডটি করতে চলেছে তার আগে ( কেননা একটি কোলন দিয়ে শেষ হবে)।

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

// Step 1. Initialization

Answer 9

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

অবশ্যই এটি সর্বদা হয় না, ইউনিকর্ন এবং রংধনু জমির বাইরে ...

কিভাবে:

foreach($critters as $creature) {
   $creature->dance();
}

কি:

/* Dancing creatures v1.0
 * 
 * The purpose of this is to make all your critters do the funky dance.
 */

foreach($critters as $creature) {
  $creature->dance();
}

কেন:

// We had to store the items in an array of objects because of _____ (reason)
foreach($critters as $creature) {
   $creature->dance();
}

Comments

এই প্রশ্ন জিজ্ঞাসা উত্তর কিভাবে?

— gnat

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

— জুহা আনটিনেন

প্রশ্নটি বেশ কয়েকবার উদাহরণের জন্য জিজ্ঞাসা করে। এটিকে আরও কার্যকর করার জন্য আপনি এই উত্তরে একটি উদাহরণ যুক্ত করতে পারেন?

— ব্রায়ান ওকলে

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

— ব্রেন্ডন লং

Answer 10

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

তাই আমার কাছে একটি সাধারণ মন্তব্য দেখতে কিছুটা ভালো লাগে

/*** Functionname
/*   What happens here
/*  [in] Params
/*  [out] params
/*** 

আমি কেবলমাত্র কেন মন্তব্যে এমন জিনিস ব্যবহার করতাম যা বুঝতে পারা শক্ত এবং কখনও কখনও প্রোগ্রামারের কাছেও "এইটিকে স্পর্শ করবেন না! কারণ ..." বা "লাইনটি যদি মুছে ফেলা হয় তবে প্রোগ্রামটি ক্র্যাশ করবে ..."

ওয়ার্কআরাউন্ডস, হ্যাকস এবং অদ্ভুত আচরণ আমার চোখে কেন মাপদণ্ডের জন্য যোগ্য ...

একটি খুব ভাল এবং এমনকি হাস্যকর উদাহরণ হ'ল রিচার্ড নামের কোনও ব্যক্তির লেখা কিছু গণ্ডগোলের কোডের জন্য এই "কার্যকরী", অন্য কেউ এটি মুড়ে ফেলেছেন এবং কেন মন্তব্যগুলিতে ব্যাখ্যা করেছেন ... https://stackoverflow.com/a/184673/979785

দুর্ভাগ্যক্রমে বেশ কয়েকবার আছে, যেখানে আপনি ষাঁড়টি আবৃত করতে বাধ্য হন **** কারণ আপনি আসলটি স্পর্শ করতে পারবেন না, কারণ "এটি সর্বদা সেভাবেই ছিল" বা আপনার অ্যাক্সেস নেই বা ... ভাল, আপনি উদ্দেশ্যটির জন্য আসলটি ঠিক করার সময় নেই যা আসলেই ওভারহেডের জন্য যোগ্যতা অর্জন করে না।

Comments

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

— টমাস

এই সত্যটি ক্ষমা করুন, আমার মাতৃভাষায় মন্তব্য এবং ডকুমেন্টেশন মন্তব্যটি বিনিময়যোগ্যভাবে ব্যবহৃত হয় এবং তাই আমি ধরেছিলাম যে ট্যাগ সহ এটি এই প্রশ্নের পাশাপাশি প্রযোজ্য। আসলেই কি ডাউনটোট করার কারণ?

— AnyOneElse

প্রশ্ন উদাহরণের জন্য বার কয়েক জিজ্ঞেস কেন মন্তব্য, কিন্তু শুধুমাত্র উদাহরণস্বরূপ আপনি অন্তর্ভুক্ত একটি হল কি মন্তব্য। উদাহরণগুলির জন্য উত্তরগুলি স্কিমিং করা লোকেরা আপনার উদাহরণ দ্বারা বিভ্রান্ত হতে পারে। আপনি কেন মন্তব্যের উদাহরণ দিতে পারেন ?

— ব্রায়ান ওকলে

যদিও আমি বলেছিলাম যে আমার কোডটিতে খুব কম সংখ্যক ডাব্লুএইচইউই রয়েছে, এবং আমি দুটি উদাহরণের নাম দিয়েছি: সম্পাদনা করুন ... এখানে একটি লিঙ্ক দেওয়া হয়েছে, এটি অবশ্যই

— WHW- এর

পছন্দ করেছেন আমি এখানে আসার আগে সেখানে ছিল।

— টমাস

Answer 11

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

কোডারের উদ্দেশ্য আরও একটি বিষয়। সরল, পরিষ্কার, সোজা কোডে অভিপ্রায়টি সুস্পষ্ট। যে কোনও যুক্তিসঙ্গত দক্ষ দক্ষ পাঠক কেবল কোড পড়ে কেবল একটি ব্লকের কোডের অভিপ্রায় পৌঁছে দেবে। বেশিরভাগ কোড এই জাতীয় পড়া উচিত।

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

Comments

প্রশ্ন উদাহরণের জন্য কয়েক বার জিজ্ঞাসা। এটিকে আরও কার্যকর করার জন্য আপনি কি নিজের উত্তরে একটি উদাহরণ যুক্ত করতে পারেন?

— ব্রায়ান ওকলে

Answer 12

এই সমস্যাটি এখনই একটি জটিল এবং কিছুটা বিশৃঙ্খল ডেটা মডেলটির বিরুদ্ধে সঞ্চিত পদ্ধতি এবং দর্শনগুলির মাধ্যমে লোড হচ্ছে।

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

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

সুতরাং হ্যাঁ, জটিল সংশ্লেষিত ডেটা মডেল এবং লোমশ ভিজ এবং একাধিক বৈধ নামযুক্ত পাথের সাথে সঞ্চিত পদ্ধতি, কেন Gd এর ভালবাসার জন্য দয়া করে তা আমাদের জানান।

Answer 13

আমি এই মন্তব্যটি লিখেছি; এটা ব্যাখ্যা একটি কংক্রিট উদাহরণ কেন কোড একটি লাইন কি এটা হয় এবং বিশেষ করে কেন আমি এটি পরিবর্তন করেছেন।

পদ্ধতিটি সঞ্চিত ডেটা পরীক্ষা করে এবং মূল্যায়ন করে যে এটি একদিকে বর্তমান সময়ের মধ্যে এবং অন্য প্রান্তে শুরুর তারিখের মাধ্যমে সম্পূর্ণ কিনা।

// In principal, this should be ">=", as we may have data up to the account start
// date but not complete for that day; in practice, 98% of the time if we have
// data for the start date it *is* complete, and requerying it would be a waste
// of time.
while (endDate > accountStartDate)
    ...

আপনি সম্ভবত অনুমান করতে পারেন, বৃহত্তর-অপারেটরটি বৃহত্তর বা সমান ছিল। মন্তব্যে ব্যাখ্যা করা হয়েছে কেন পুরানো মানটি বোঝায় এবং কেন নতুন মান আরও ভাল। ভবিষ্যতে যদি কেউ এটিকে দেখেন তবে তারা দেখতে পাবেন যে ">" এর ব্যবহার কোনও তদারকি নয়, তবে একটি অপ্টিমাইজেশন। তারপরে তারা সেই সময়ের প্রয়োজনের ভিত্তিতে এটি পরিবর্তন করতে বা ছেড়ে দিতে পারে।