জটিল কোড ব্যাখ্যা করে এমন মন্তব্যে কী ভুল?


236

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

আমার প্রশ্নটি নিম্নলিখিত:

একটি জটিল অ্যালগরিদম বা বর্ণনামূলক মন্তব্য সহ একটি দীর্ঘ এবং সংশ্লেষিত কোডের টুকরো ব্যাখ্যা করার ক্ষেত্রে কী ভুল?

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

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

সুতরাং আংশিকভাবে মানব-পঠনযোগ্য প্রোগ্রামিং ভাষায় লিখিত জটিল একটি টুকরো কোড লেখার পরে, কেন বন্ধুত্বপূর্ণ এবং বোধগম্য ইংরেজিতে কোডটির পরিচালনা সম্পর্কিত ব্যাখ্যা এবং সংক্ষিপ্ত মন্তব্য যুক্ত করবেন না?

কেউ কেউ বলবেন "কোড বোঝা শক্ত হওয়া উচিত নয়", "ফাংশনগুলি ছোট করা", "বর্ণনামূলক নাম ব্যবহার করুন", "স্প্যাগেটি কোড লিখবেন না"।

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

এটি সাধারণ অপারেশন সম্পর্কে কয়েকটি লাইনের মন্তব্যে জটিল অ্যালগরিদমকে ব্যাখ্যা করা কি সত্যই খারাপ? একটি মন্তব্যে জটিল কোডটি ব্যাখ্যা করার ক্ষেত্রে কী ভুল?


14
যদি এটি বিশৃঙ্খলা হয় তবে এটিকে ছোট ছোট টুকরো করে পুনরায় ব্যবহারের চেষ্টা করুন।
ভান হিলস

151
তত্ত্বের ক্ষেত্রে তত্ত্ব এবং অনুশীলনের মধ্যে কোনও পার্থক্য নেই। অনুশীলনে, আছে।
স্কট লিডলি

5
@ ম্যাটনজ: আরও সরাসরি, আপনি মন্তব্যটি লেখার সময় আপনি এই কোডটি সমাধান করেন এমন সমস্যায় ডুবে আছেন। পরবর্তী বার আপনি পরিদর্শন করার সময়, এই সমস্যাটির সাথে আপনার ক্ষমতা কম থাকবে ।
স্টিভ জেসপ

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

11
আমি অনুভব করি যে নীচের অনেক প্রতিক্রিয়া উদ্দেশ্যমূলকভাবে আপনার প্রশ্নের ভুল ব্যাখ্যা করছে। আপনার কোড মন্তব্য করে কোন ভুল নেই। যদি আপনার মনে হয় আপনার একটি ব্যাখ্যামূলক মন্তব্য লিখতে হবে তবে আপনার এটি করা দরকার।
টনি এনিস

উত্তর:


408

সাধারণ লোকের পদে:

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

শেষের সারি:

নিজেকে ব্যাখ্যা করা ভাল, এমনটা করার দরকার নেই আরও ভাল।


91
যখন কোনও ভাল মন্তব্য খুব কম সময়ে কাজটি করতে পারে তখন নিয়োগকর্তার অর্থের পুনর্লিখনের কোডটি আরও স্ব-বর্ণনামূলক হওয়ার পক্ষে যুক্তিযুক্ত হওয়া প্রায়শই অসম্ভব। একজন কর্তব্যসূচক প্রোগ্রামারকে অবশ্যই তার প্রতিবার / তার রায় ব্যবহার করতে হবে।
আইকোলি

34
@ এ্যাকোলি দিয়ে স্ব-ব্যাখ্যামূলক কোড লেখা শুরু করা আরও ভাল।
তুলাইনস কর্ডোভা

127
কখনও কখনও স্ব-ব্যাখ্যামূলক কোড আজকের এইচডাব্লুএন্ডএসডাব্লুয়ের সাথে কোনও সমস্যার সমাধান করার জন্য যথেষ্ট দক্ষ নয়। এবং ব্যবসায়ের যুক্তি কুখ্যাত ... কুঁচকানো। মার্জিত সফ্টওয়্যার সমাধান রয়েছে এমন সমস্যাগুলির উপসেটটি সমাধানের জন্য অর্থনৈতিকভাবে কার্যকর এমন সমস্যার সংস্থার তুলনায় উল্লেখযোগ্য পরিমাণে ছোট।
স্কট লিডলি

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

29
@ ইউজার 18১ that৫২ বাদে আপনার কাছে যা কেবলমাত্র সেই কোডটি লিখেছিলেন এবং এতে নিমগ্ন শেষ সময়টি আপনার পক্ষে স্বতঃস্ফূর্ত তা বাদ দিয়ে আপনি এখন থেকে পাঁচ বছর ধরে এটি বজায় রাখতে বা সম্পাদনা করতে পারেন তা আপনার নিজের পক্ষে ব্যাখ্যাযোগ্য হতে পারে না, সমস্ত কিছু ছেড়ে দিন সম্ভাব্য লোকেরা যারা আপনি নন তাদের এটি দেখতে হবে। "স্ব-ব্যাখ্যামূলক" সংজ্ঞাগুলির একটি নেবুলাস পবিত্র গিল।
শাদুর

110

কোড জটিল বা বিভ্রান্ত হওয়ার বিভিন্ন কারণ রয়েছে। সবচেয়ে সাধারণ কারণ সেরা এটি কম, বিভ্রান্তিকর কোনো ধরনের মন্তব্য যোগ করে না করতে কোড refactoring দ্বারা সম্বোধন করা হয়।

তবে, এমন কিছু ক্ষেত্রে রয়েছে যেখানে একটি সুনির্বাচিত মন্তব্যটি সেরা পছন্দ।

  • যদি এটি নিজেই অ্যালগরিদম হয় যা জটিল এবং বিভ্রান্তিকর হয় তবে এটির প্রয়োগই নয় - গণিত জার্নালে লেখার মতো এবং এমবোগোর অ্যালগোরিদম হিসাবে পরিচিত হওয়ার পরে — তাহলে আপনি বাস্তবায়নের একেবারে শুরুতে একটি মন্তব্য রেখেছিলেন, পড়া "এটি মূলত এখানে বর্ণিত রিফ্রোবিনিকেটিং উইজেটগুলির জন্য এমবোগোর অ্যালগরিদম: [কাগজের ইউআরএল] This এই প্রয়োগে অ্যালিস এবং ক্যারল [অন্য একটি কাগজের ইউআরএল] দ্বারা পরিমার্জন রয়েছে" " এর চেয়ে আর কোনও বিশদে যাওয়ার চেষ্টা করবেন না; কারও যদি আরও বিশদ প্রয়োজন হয় তবে তাদের সম্ভবত পুরো কাগজটি পড়া দরকার।

  • যদি আপনি এমন কিছু গ্রহণ করেন যা কিছু বিশেষায়িত স্বরলিপিতে এক বা দুটি লাইন হিসাবে রচনা করা যায় এবং এটিকে আবশ্যক কোডের একটি বৃহত্তর গ্লোবগুলিতে প্রসারিত করা হয়, তবে ফাংশনের উপরে একটি মন্তব্যে সেই এক বা দুটি লাইন রেখে দেওয়া ভাল উপায় to এটি করার কথা পাঠককে বলুন । এটি "তবে মন্তব্যটি কোডের সাথে সিঙ্কের বাইরে চলে গেলে কী হবে" এর একটি ব্যতিক্রম, কারণ বিশেষায়িত নোটেশনটি সম্ভবত কোডের চেয়ে বাগগুলি খুঁজে পাওয়া খুব সহজ। (আপনি যদি এর পরিবর্তে ইংরেজীতে কোনও স্পেসিফিকেশন লিখে থাকেন তবে এটি অন্যভাবে।) একটি ভাল উদাহরণটি এখানে: https://dxr.mozilla.org/mozilla-central/source/layout/style/nsCSSScanner.cpp#1057 ...

    /**
     * Scan a unicode-range token.  These match the regular expression
     *
     *     u\+[0-9a-f?]{1,6}(-[0-9a-f]{1,6})?
     *
     * However, some such tokens are "invalid".  There are three valid forms:
     *
     *     u+[0-9a-f]{x}              1 <= x <= 6
     *     u+[0-9a-f]{x}\?{y}         1 <= x+y <= 6
     *     u+[0-9a-f]{x}-[0-9a-f]{y}  1 <= x <= 6, 1 <= y <= 6
    
  • কোড সামগ্রিক সহজবোধ্য, তবে একটি বা দুটি জিনিস যে থাকে চেহারা বেজায় সংবর্ত, অনাবশ্যক, অথবা শুধু সাধারণ ভুল, কিন্তু কারণ কারণ যে উপায় হতে থাকে, তখন আপনি কি একটি মন্তব্য অবিলম্বে উপরে সন্দেহজনক সুদর্শন বিট, যা রাখা আপনি কারণ বর্ণনা । এখানে একটি সহজ উদাহরণ, যেখানে ধ্রুবকের নির্দিষ্ট মান কেন কেবলমাত্র সেই বিষয়টির ব্যাখ্যা প্রয়োজন।

    /* s1*s2 <= SIZE_MAX if s1 < K and s2 < K, where K = sqrt(SIZE_MAX+1) */
    const size_t MUL_NO_OVERFLOW = ((size_t)1) << (sizeof(size_t) * 4);
    if ((nmemb >= MUL_NO_OVERFLOW || size >= MUL_NO_OVERFLOW) &&
        nmemb > 0 && SIZE_MAX / nmemb < size)
      abort();
    

25
এটি একটি আক্রোশ, ;-) 4হওয়া উচিতCHAR_BIT / 2
স্টিভ জেসপ

@ স্টিভ জেসোপ: CHAR_BITS16 এবং সাইজের (সাইজ_টি) 2 হ'ল এমন কোনও বাস্তবায়ন কি থামিয়ে দেবে, তবে আকার_t এর সর্বাধিক মান যেমন 2 ^ 20 [আকার_t 12 টি প্যাড বিট সমেত] ছিল?
ক্যাট

2
@supercat আমি কিছুই স্পষ্টত precludes যে C99 মধ্যে যার মানে উদাহরণস্বরূপ দেখতে না হয় টেকনিক্যালি ভুল। এটি ওপেনবিএসডি'র (কিছুটা পরিবর্তিত সংস্করণ) থেকে নেওয়া হয়েছে reallocarrayএবং ওপেনবিএসডি সাধারণত তাদের সম্ভাব্যতাগুলি সরবরাহ করতে বিশ্বাস করে না যা তাদের এবিআইতে ঘটে না ।
zwol

3
@ জ্যাক: কোডটি পসিক্স অনুমানের আশেপাশে তৈরি করা হয়েছে, CHAR_BITS ব্যবহার করে কোডটি 8.. ব্যতীত অন্য মানগুলির সাথে কাজ করতে পারে এমন ধারণা তৈরি করতে পারে
সুপারক্যাট

2
@ জ্যাক: সঠিক-প্রস্থের স্বাক্ষরবিহীন প্রকারের দরকারী হওয়ার জন্য, তাদের শব্দার্থবিজ্ঞানের আকারের তুলনায় স্বতন্ত্রভাবে সংজ্ঞায়িত করা দরকার int। যেমনটি দেওয়া হয় uint32_t x,y,z;, এর অর্থ (x-y) > zআকারের উপর নির্ভর করে int। তদ্ব্যতীত, দৃ writing় কোড লেখার জন্য ডিজাইন করা কোনও ভাষাতে প্রোগ্রামারদের এমন একটি পার্থক্যের মধ্যে পার্থক্য করার সুযোগ দেওয়া উচিত যেখানে গণনাগুলি প্রকারের সীমা অতিক্রম করতে পারে এবং নিঃশব্দে মোড়ানো উচিত, যেখানে প্রকারের সীমা অতিক্রম করা গণনাগুলি ফাঁদে ফেলা উচিত, যেখানে একটি বিভাজন হয় প্রকারের সীমাটি অতিক্রম করার আশা করা হয় না তবে ...
সুপারক্যাট

61

সুতরাং একটি মন্তব্যে জটিল কোডটি ব্যাখ্যা করার ক্ষেত্রে কী ভুল?

এটি উইকিপিডিয়া নিবন্ধে সংজ্ঞায়িত হিসাবে এটি সঠিক বা ভুল সম্পর্কিত নয়, তবে 'সেরা অনুশীলনের' প্রশ্ন :

একটি সেরা অনুশীলন হ'ল একটি পদ্ধতি বা কৌশল যা নিয়মিতভাবে ফলাফলগুলি অন্য উপায়ে অর্জনের তুলনায় উন্নত দেখায় এবং এটি একটি মানদণ্ড হিসাবে ব্যবহৃত হয়।

সুতরাং সর্বোত্তম অনুশীলন হ'ল প্রথমে কোডটি উন্নত করার চেষ্টা করা এবং যদি সম্ভব না হয় তবে ইংরেজি ব্যবহার করা।

এটি কোনও আইন নয়, তবে মন্তব্য কোডের জন্য রিফ্যাক্টরিং কোডের চেয়ে রিফ্যাক্টরিং দরকার এমন মন্তব্য করা কোড পাওয়া অনেক বেশি সাধারণ, সেরা অনুশীলন এটি প্রতিফলিত করে।


42
+1 এর জন্য "মন্তব্য করা কোডের জন্য রিফ্যাক্টরিংয়ের প্রয়োজন এমন মন্তব্য কোডটি পাওয়া আরও সাধারণ বিষয় যা" মন্তব্যগুলির প্রয়োজন "
ব্র্যান্ডন

7
ঠিক আছে, তবে কতবার সেই মন্তব্যটি হয়: //This code seriously needs a refactor
এরিক রিপেন

2
অবশ্যই, কঠোর বৈজ্ঞানিক অধ্যয়নের দ্বারা সমর্থিত কোনও তথাকথিত সেরা অনুশীলন নিছক একটি মতামত।
blrfl

54

এমন এক দিন আসবে যখন আপনার সুন্দর, নিখুঁতভাবে তৈরি, ভাল কাঠামোগত এবং পঠনযোগ্য কোডটি কাজ করবে না। অথবা এটি যথেষ্ট ভাল কাজ করবে না। অথবা একটি বিশেষ কেস তৈরি হবে যেখানে এটি কাজ করে না এবং সমন্বয় প্রয়োজন needs

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

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

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

সুতরাং আমি মন্তব্যগুলিকে খারাপ কোডের জন্য ক্ষমা হিসাবে মনে করি না, তবে আপনি কেন স্পষ্টত কাজটি করেন নি তার ব্যাখ্যা হিসাবে হতে পারে। থাকার কারণে // The standard approach doesn't work against the 64 bit version of the Frobosticate Libraryভবিষ্যতের বিকাশকারীদের, আপনার ভবিষ্যতের স্ব সহ, কোডের সেই অংশটির দিকে মনোযোগ দেওয়ার এবং সেই লাইব্রেরির বিরুদ্ধে পরীক্ষার অনুমতি দেবে। অবশ্যই, আপনি মন্তব্যগুলি আপনার উত্স নিয়ন্ত্রণ নিয়ন্ত্রণেও রাখতে পারেন তবে কিছু ভুল হয়ে যাওয়ার পরে লোকেরা কেবল সেগুলি দেখবে। কোড পরিবর্তন করার সাথে সাথে তারা কোডের মন্তব্যগুলি পড়বে।

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

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


5
@ খ্রিস্টিয়ান এটা কি? প্রথম লাইনটি অবশ্যই এই বিবৃতিটির উল্লেখ করে, তবে এর বাইরে এটি যতটা বুঝি ততই এটি আরও বিস্তৃত।
গ্লেনাট্রন

9
"আমি শপথ করছি আমার অতীত স্ব স্ব আসল মূর্খতা আমি যখনই লিখেছি পুরানো কোডটি পড়ি।" আমার বিকাশের ক্যারিয়ারের চার বছর এবং আমি মনে করি এটি এমন একটি ঘটনা যা যখনই আমি 6 মাস বা তার বেশি বয়স্ক কোনও কিছুর দিকে তাকাই।
কেন

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

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

1
@ লিলিয়েনথাল, আমি মনে করি না যে শেষ প্যারাটি ব্যক্তিগত প্রকল্পের মধ্যে সীমাবদ্ধ - তিনি বলেছিলেন "... আমি এখনও এমন অংশগুলিকে মন্তব্য করি যা আমি বিভ্রান্তিকর বলে মনে করি।"
ওয়াইল্ডকার্ড

29

মন্তব্যের প্রয়োজনীয়তা কোডের বিমূর্ততা স্তরের বিপরীতভাবে সমানুপাতিক।

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

main:   
; initializes the two numbers and the counter.  Note that this assumes
; that the counter and num1 and num2 areas are contiguous!
;
    mov ax,'00'                     ; initialize to all ASCII zeroes
    mov di,counter                  ; including the counter
    mov cx,digits+cntDigits/2       ; two bytes at a time
    cld                             ; initialize from low to high memory
    rep stosw                       ; write the data
    inc ax                          ; make sure ASCII zero is in al
    mov [num1 + digits - 1],al      ; last digit is one
    mov [num2 + digits - 1],al      ; 
    mov [counter + cntDigits - 1],al

    jmp .bottom         ; done with initialization, so begin

.top
    ; add num1 to num2
    mov di,num1+digits-1
    mov si,num2+digits-1
    mov cx,digits       ; 
    call    AddNumbers  ; num2 += num1
    mov bp,num2         ;
    call    PrintLine   ;
    dec dword [term]    ; decrement loop counter
    jz  .done           ;

    ; add num2 to num1
    mov di,num2+digits-1
    mov si,num1+digits-1
    mov cx,digits       ;
    call    AddNumbers  ; num1 += num2
.bottom
    mov bp,num1         ;
    call    PrintLine   ;
    dec dword [term]    ; decrement loop counter
    jnz .top            ;
.done
    call    CRLF        ; finish off with CRLF
    mov ax,4c00h        ; terminate
    int 21h             ;

এমনকি মন্তব্য সহ, এটি আঁকাবাঁকা করা বেশ জটিল হতে পারে।

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

^(((ht|f)tp(s?))\://)?(www.|[a-zA-Z].)[a-zA-Z0-9\-\.]+\.(com|edu|gov|m
+il|net|org|biz|info|name|museum|us|ca|uk)(\:[0-9]+)*(/($|[a-zA-Z0-9\.
+\,\;\?\'\\\+&amp;%\$#\=~_\-]+))*$

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

আমি চিন্তা করছি সি সংখ্যাসূচক রেসিপি বেশিরভাগই করার ধারণকৃত অনূদিত সি ++ সাংখ্যিক রেসিপি , যা আমি অনুমান হিসাবে শুরু করেন সংখ্যাসূচক রেসিপি (FORTAN মধ্যে), সমস্ত ভেরিয়েবল সঙ্গে a, aa, b, c, cc, ইত্যাদি প্রত্যেকটি সংস্করণ মাধ্যমে বজায় রেখেছিল। অ্যালগরিদমগুলি সঠিক হতে পারে তবে তারা প্রদত্ত ভাষাগুলির বিমূর্ততার সুবিধা নেয় নি। এবং তারা পি *** আমাকে বন্ধ। ডাঃ ডবস নিবন্ধের নমুনা - ফাস্ট ফুরিয়ার ট্রান্সফর্ম :

void four1(double* data, unsigned long nn)
{
    unsigned long n, mmax, m, j, istep, i;
    double wtemp, wr, wpr, wpi, wi, theta;
    double tempr, tempi;

    // reverse-binary reindexing
    n = nn<<1;
    j=1;
    for (i=1; i<n; i+=2) {
        if (j>i) {
            swap(data[j-1], data[i-1]);
            swap(data[j], data[i]);
        }
        m = nn;
        while (m>=2 && j>m) {
            j -= m;
            m >>= 1;
        }
        j += m;
    };

    // here begins the Danielson-Lanczos section
    mmax=2;
    while (n>mmax) {
        istep = mmax<<1;
        theta = -(2*M_PI/mmax);
        wtemp = sin(0.5*theta);
        wpr = -2.0*wtemp*wtemp;
        wpi = sin(theta);
        wr = 1.0;
        wi = 0.0;
        for (m=1; m < mmax; m += 2) {
            for (i=m; i <= n; i += istep) {
                j=i+mmax;
                tempr = wr*data[j-1] - wi*data[j];
                tempi = wr * data[j] + wi*data[j-1];

                data[j-1] = data[i-1] - tempr;
                data[j] = data[i] - tempi;
                data[i-1] += tempr;
                data[i] += tempi;
            }
            wtemp=wr;
            wr += wr*wpr - wi*wpi;
            wi += wi*wpr + wtemp*wpi;
        }
        mmax=istep;
    }
}

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

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


1
কেউ সত্যিই সমাবেশ ভাষায় এই মত একটি লাইন লেখা করা উচিত: dec dword [term] ; decrement loop counter। অন্যদিকে, আপনার সমাবেশ ভাষার উদাহরণটি কী অনুপস্থিত তা হ'ল প্রতিটি "কোড অনুচ্ছেদে" এর আগে একটি মন্তব্য যা পরবর্তী কোডের পরবর্তী ব্লকটি কী করে তা ব্যাখ্যা করে। সেক্ষেত্রে, মন্তব্যটি সাধারণত সিউডোকোডের একটি এক লাইনের সমতুল্য হবে, যেমন ;clear the screenপর্দা সাফ করার জন্য এটি 7 লাইনের পরে অনুসরণ করবে।
স্কট হুইটলক

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

মানে ^(((ht|f)tps?)\:\/\/)?(www\.)*[a-zA-Z0-9\-\.]+\.(com|edu|gov|mil|net|org|biz|info|name|museum|us|ca|uk)(\:[0-9]+)*(\/($|[a-zA-Z0-9\.\,\;\?\'\\\+&%\$#\=~_\-]+))*$? সংখ্যার ঠিকানা সম্পর্কে সচেতন হন।
ইজাবেরে

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

3
+1: "The need for comments is inversely proportional to the abstraction level of the code." বেশ কিছুটা এখানে ঠিক আছে।
জেরাত

21

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

মন্তব্যে সমস্যা আছে - আপনার উল্লেখ করা কোড আপডেট করার সাথে আপনাকে সেগুলি আপডেট রাখতে হবে যা খুব কমই ঘটে। আপনার কোড সম্পর্কে পুঙ্খানুপুঙ্খ ডকুমেন্টেশনের জন্য উইকি বা কিছু হ'ল একটি উপযুক্ত উত্স। আপনার কোড মন্তব্যগুলির প্রয়োজন ছাড়াই পঠনযোগ্য হওয়া উচিত। সংস্করণ নিয়ন্ত্রণ বা সংশোধন নোটগুলি যেখানে আপনার কোড পরিবর্তনগুলি বর্ণনা করে সেখানে হওয়া উচিত।

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


18

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

(1) একটি জটিল অ্যালগরিদম বা (2) একটি বর্ণনামূলক মন্তব্য সহ একটি দীর্ঘ এবং সংশ্লেষিত কোডের ব্যাখ্যা দিয়ে কী ভুল?

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

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

মার্টিন এই জাতীয় কোডের কথা বলছেন। এবং তিনি আপনার প্রশ্নের সাথে অধ্যায়ের শীর্ষে কর্নিগান এবং প্লেগ্রারের উদ্ধৃতি দিয়ে সম্বোধন করেছেন:

খারাপ কোড মন্তব্য করবেন না it এটি আবার লিখুন।

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

এবং এটিই মার্টিন বলেছেন:

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

এটি আপনার (2)। মার্টিন সম্মত হন যে দীর্ঘ, সংশ্লেষিত কোডের মন্তব্যগুলির দরকার নেই - তবে তিনি প্রোগ্রামটির কাঁধে এই কোডটির জন্য দোষ চাপিয়েছিলেন, যিনি এটি লিখেছিলেন, "আমরা সবাই জানি এটি যথেষ্ট নয়"। তিনি যুক্তি দেখান যে:

কয়েকটি মন্তব্যে পরিষ্কার এবং অভিব্যক্তিক কোড প্রচুর মন্তব্য সহ বিশৃঙ্খল এবং জটিল কোডের চেয়ে অনেক বেশি উন্নত। আপনার তৈরি করা জগাখিখি বিশিষ্ট মন্তব্যগুলিতে আপনার সময় ব্যয় করার পরিবর্তে, এই জঞ্জাল পরিষ্কার করার জন্য ব্যয় করুন spend


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

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

2
@ ট্রিসিস হাহা, হ্যাঁ তবে এমন একটি পৃথিবীতে যেখানে প্রোগ্রামাররা দায়বদ্ধ এবং ব্যবসায়িক লোক নয়, তারা কখনও শিপিং করবে না কারণ তারা নিখুঁততার জন্য নিরর্থক সন্ধানে একটি ধ্রুবক রিফ্যাক্টর কোডবেসকে সোনার-ধাতুপট্টাবৃত করে রাখে।
gbjbaanb

4
@ পেট্রিকক্লিন্স ওয়েবে আমি প্রায় যা পড়েছি তা প্রথমবার এটি করার কথা doing প্রায় কেউই মেসগুলি ঠিক করার বিষয়ে নিবন্ধ লিখতে চায় না! পদার্থবিজ্ঞানীরা বলেছেন "একটি নিখুঁত ক্ষেত্র দেওয়া ..." কম্পিউটার বিজ্ঞানীরা বলেছেন "গ্রিনফিল্ডের বিকাশ দেওয়া হয়েছে ..."
gbjbaanb

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

8

একটি জটিল অ্যালগরিদম বা বর্ণনামূলক মন্তব্য সহ একটি দীর্ঘ এবং সংশ্লেষিত কোডের টুকরো ব্যাখ্যা করার ক্ষেত্রে কী ভুল?

এর মতো কিছুই নেই। আপনার কাজের ডকুমেন্টিং ভাল অনুশীলন।

এটি বলেছিল, আপনার এখানে একটি মিথ্যা দ্বিধাত্বিকতা রয়েছে: ক্লিন কোড বনাম বনাম ডকুমেন্টেড কোড লেখা - দুটি বিরোধী নয়।

"জটিল কোডটি যতক্ষণ মন্তব্য করা হচ্ছে ততক্ষণ ঠিক আছে" ভেবে চিন্তার পরিবর্তে আপনার কীসের দিকে নজর দেওয়া উচিত জটিল কোডটিকে সহজ কোডে সরলকরণ এবং বিমূর্তকরণকে বোঝানো উচিত।

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

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

সত্য। এজন্য আপনার সমস্ত পাবলিক এপিআই অ্যালগরিদমগুলি ডকুমেন্টেশনে ব্যাখ্যা করা উচিত।

সুতরাং আংশিকভাবে মানব-পঠনযোগ্য প্রোগ্রামিং ভাষায় লিখিত জটিল একটি টুকরো কোড লেখার পরে, কেন বন্ধুত্বপূর্ণ এবং বোধগম্য ইংরেজিতে কোডটির পরিচালনা সম্পর্কিত ব্যাখ্যা এবং সংক্ষিপ্ত মন্তব্য যুক্ত করবেন না?

আদর্শভাবে, কোডের একটি জটিল টুকরো লেখার পরে আপনার উচিত (সম্পূর্ণ তালিকা নয়):

  • এটিকে একটি খসড়া বিবেচনা করুন (যেমন এটি আবার লেখার পরিকল্পনা করুন)
  • অ্যালগরিদম এন্ট্রি পয়েন্ট / ইন্টারফেস / ভূমিকা / ইত্যাদি আনুষ্ঠানিককরণ (ইন্টারফেস বিশ্লেষণ এবং অনুকূলকরণ, বিমূর্ততা, নথি পূর্বশর্ত, পোস্টকন্ডিশন এবং পার্শ্ব প্রতিক্রিয়া এবং নথি ত্রুটির ক্ষেত্রে আনুষ্ঠানিক)।
  • পরীক্ষা লিখুন
  • পরিষ্কার এবং রিফ্যাক্টর

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

[...] কিছু অ্যালগোরিদম জটিল। এবং তাই লাইন দ্বারা লাইন পড়ার সময় তাদের বোঝা শক্ত।

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

এটি সাধারণ অপারেশন সম্পর্কে কয়েকটি লাইনের মন্তব্যে জটিল অ্যালগরিদমকে ব্যাখ্যা করা কি সত্যই খারাপ?

না - এটা ভাল। মন্তব্য কয়েক লাইন যোগ যদিও যথেষ্ট নয়।

একটি মন্তব্যে জটিল কোডটি ব্যাখ্যা করার ক্ষেত্রে কী ভুল?

আপনার জটিল কোড থাকা উচিত নয় এই বিষয়টি যদি এড়ানো যায়।

জটিল কোড এড়ানোর জন্য, আপনার ইন্টারফেসগুলি আনুষ্ঠানিক করুন, বাস্তবায়নের জন্য ব্যয় করার চেয়ে API ডিজাইনের জন্য ~ 8 গুণ বেশি ব্যয় করুন (স্টেপানোভ কমপক্ষে 10x ইন্টারফেসের সাথে প্রয়োগের সাথে তুলনা করার পরামর্শ দিয়েছেন), এবং এই জ্ঞানের সাথে একটি প্রকল্প বিকাশের দিকে যান আপনি একটি প্রকল্প তৈরি করছেন, কেবল কিছু অ্যালগরিদম লিখছেন না।

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


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

6

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

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

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

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

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


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

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

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

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

2
@ স্নোম্যান লোকেরা পরিবর্তনশীল নামের সাথে এটি করতে পারে। আমি কোডটি দেখেছি যেখানে ভেরিয়েবল তালিকাঅফ অ্যাপ্লিকেশনগুলিতে কলাগুলির একটি তালিকা রয়েছে। কেউ অ্যাপলের তালিকা প্রসেসিং কোডটি অনুলিপি করে এবং ভেরিয়েবলের নাম পরিবর্তন করে বিরক্ত না করে কলাতে এটি রূপান্তরিত করে।
ফ্লোরিয়ান এফ

5

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

// This code implements the algorithm described in requirements document 239.

এমনকি ঠিক

void doPRD239Algorithm() { ...

অবশ্যই লোকেরা নামযুক্ত ফাংশন MatchStringKnuthMorrisPrattবা encryptAESবা দ্বারা খুশি partitionBSP। আরও অস্পষ্ট নামগুলি একটি মন্তব্যে ব্যাখ্যা করার মতো। আপনি গ্রন্থপঞ্জি সংক্রান্ত ডেটা এবং কোনও কাগজের সাথে একটি লিঙ্কও যুক্ত করতে পারেন যা থেকে আপনি একটি অ্যালগরিদম প্রয়োগ করেছেন।

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

কোডের আরও একটি বিভাগ রয়েছে যা আমলাতান্ত্রিকের মতো এত অ্যালগরিদমিক নয়। আপনাকে অন্য সিস্টেমের জন্য প্যারামিটার সেট আপ করতে হবে, বা অন্য কারও বাগের সাথে আন্তঃসংযোগ স্থাপন করতে হবে:

/* Configure the beam controller and turn on the laser.
The sequence is timing-critical and this code must run with interrupts disabled.
Note that the constant 0xef45ab87 differs from the vendor documentation; the vendor
is wrong in this case.
Some of these operations write the same value multiple times. Do not attempt
to optimise this code by removing seemingly redundant operations.
*/

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

5

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

আমি বিশ্বাস করি আপনার অ্যালগরিদম নয়, আপনার অভিপ্রায়টি মন্তব্য করা উচিত । অর্থাৎ আপনি কী করতে চেয়েছিলেন তা নয়, আপনি কী করছেন তার উপরে মন্তব্য করুন

উদাহরণ স্বরূপ:

// The getter.
public <V> V get(final K key, Class<V> type) {
  // Has it run yet?
  Future<Object> f = multitons.get(key);
  if (f == null) {
    // No! Make the task that runs it.
    FutureTask<Object> ft = new FutureTask<Object>(
            new Callable() {

              public Object call() throws Exception {
                // Only do the create when called to do so.
                return key.create();
              }

            });
    // Only put if not there.
    f = multitons.putIfAbsent(key, ft);
    if (f == null) {
      // We replaced null so we successfully put. We were first!
      f = ft;
      // Initiate the task.
      ft.run();
    }
  }
  try {
    /**
     * If code gets here and hangs due to f.status = 0 (FutureTask.NEW)
     * then you are trying to get from your Multiton in your creator.
     *
     * Cannot check for that without unnecessarily complex code.
     *
     * Perhaps could use get with timeout.
     */
    // Cast here to force the right type.
    return (V) f.get();
  } catch (Exception ex) {
    // Hide exceptions without discarding them.
    throw Throwables.asRuntimeException(ex);
  }
}

এখানে প্রতিটি পদক্ষেপ যা সম্পাদন করে তা জানানোর কোনও চেষ্টা নেই, এটি সমস্তটি যা বলেছিল তা হ'ল ।

পিএস: আমি যে উত্সটি উল্লেখ করছিলাম তা পেয়েছি - কোডিং হরর: কোড আপনাকে কীভাবে জানায় , মন্তব্য আপনাকে কেন বলে


8
প্রথম মন্তব্য: এটি এখনও চালানো হয়েছে? এখনও কি চালানো হয়েছে? অন্যান্য মতামত একই। কোডটি কী করে জানে না এমন কারও পক্ষে এটি অকেজো।
gnasher729

1
@ gnasher729 - প্রসঙ্গের বাইরে নেওয়া প্রায় কোনও মন্তব্যই অকেজো হবে - এই কোডটি এমন মন্তব্য যুক্ত করার একটি প্রদর্শন যা বর্ণনা করার চেষ্টা করার পরিবর্তে অভিপ্রায়কে নির্দেশ করে । আমি দুঃখিত যে এটি আপনার পক্ষে কিছুই করে না।
ওল্ড কার্মিউডজিয়ন

2
এই কোডটির রক্ষণাবেক্ষণকারীটির একটি প্রসঙ্গ থাকবে না। কোডটি কী করে তা নির্ধারণ করা বিশেষত কঠিন নয়, তবে মন্তব্যগুলি সাহায্য করছে না। আপনি মন্তব্য লিখলে আপনার সময় নিবেন এবং যখন আপনি সেগুলি লিখবেন তখন মনোনিবেশ করুন।
gnasher729

বিটিডব্লিউ - এটি কি এখনও চালিয়েছে মন্তব্যটি উল্লেখ করছে Futureএবং এটি ইঙ্গিত করে যে ইতিমধ্যে চালানো হয়েছে কিনা তা সনাক্ত করার get()বিরুদ্ধে একটি চেক অনুসরণ করা হয়েছে - প্রক্রিয়াটির চেয়ে অভিপ্রায়টিকে সঠিকভাবে ডকুমেন্টিং করা । nullFuture
ওল্ড কার্মিউডজিয়ন

1
@ ওल्डকুরিমডজিয়ন: আপনার উত্তরটি আমি যা ভাবছিলাম তার নিকটবর্তী, আমি আপনার বক্তব্যের উদাহরণ হিসাবে এই মন্তব্যটি যুক্ত করব। ক্লিন কোড ব্যাখ্যা করার জন্য কোনও মন্তব্যের প্রয়োজন নেই, তবে কোডিং কেন অন্যভাবে করা হয়েছে তা কেন ব্যাখ্যা করা ভাল। আমার সীমিত অভিজ্ঞতায়, কোডগুলি কোডটি যে কাজ করছে তা নির্ধারণ করা বা ব্যবসার বিধি দ্বারা কোডটি প্রয়োগের উদ্দেশ্যে বোঝানো হয়েছে এমন আইডিয়াসিন্যাসিকে ব্যাখ্যা করতে প্রায়শই দরকারী। কোনও ত্রুটি সংশোধন করার জন্য যুক্ত করা কোডের মন্তব্য করা একটি ভাল উদাহরণ, যদি বাগটি ঘটে থাকে কারণ ডেটা সম্পর্কে ধারণা অনুমান করা ভুল ছিল।
র্যান্ডল স্টুয়ার্ট

4

তবে আমরা সবাই জানি যে যথেষ্ট নয়।

সত্যি? কখন থেকে?

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

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


7
আমি জানি এটি যথেষ্ট নয়।
ফ্লোরিয়ান এফ

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

3
আমি অন্য লোকদের কোডটি বোঝার চেষ্টা করি যাঁর আমি ইচ্ছা করি প্রতি দুই বছরে একবারে আরও কিছু মন্তব্য যুক্ত করেছিলাম।
ওগ্রে গীতসংহিতা 33

@ ওগ্রেপস্লাম 33 - তাদের কি ছোট পদ্ধতি আছে এবং ভাল নাম ব্যবহার করা হয়? খারাপ কোড খারাপ, মন্তব্য নির্বিশেষে।
টেলাস্টিন

2
@ টেলাস্টিন দুর্ভাগ্যক্রমে, একটি বড় কোড বেসে কাজ করার সময়, "ছোট" পদ্ধতিগুলি এবং "ভাল" নামগুলি প্রতিটি বিকাশকারীকে বিষয়গত করে (তাই এই বিষয়ে ভাল মন্তব্য) is একজন বিকাশকারী lar বছরের জন্য ফ্লারবিগান গ্রাফিকাল প্রসেসিং অ্যালগরিদম কোড লিখছেন, তাঁর এবং অনুরূপ বিকাশকারীদের কাছে পুরোপুরি স্পষ্ট কিছু লিখতে পারেন, তবে পার্বিয়ান গ্রিড অবকাঠামো কোডটি বিকাশের জন্য গত 4 বছর অতিবাহিত নতুন লোকটির কাছে এটি রহস্যজনক হবে। তারপরে, 2 সপ্তাহ পরে, ফ্লারবিগান বিশেষজ্ঞ ত্যাগ করেন।
ওগ্রে গীতসংহিতা 33

2

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

বলা হচ্ছে, উত্সের মন্তব্যগুলি অন্যান্য প্রোগ্রামারদের (নিজেকে সহ) ডকুমেন্টেশনের একধরণের। কোডগুলি প্রতিটি পদক্ষেপে কী করছে তার চেয়ে যদি মন্তব্যগুলি আরও বিমূর্ত বিষয় সম্পর্কে হয় তবে আপনি গড়ের চেয়ে ভাল করছেন। বিমূর্ততার সেই স্তরটি আপনি যে সরঞ্জামটি ব্যবহার করছেন তার সাথে পরিবর্তিত হয়। সমাবেশ ভাষা রুটিনের সাথে মতামতগুলির সাথে সাধারণত নীচের স্তরের "বিমূর্ততা" থাকে, উদাহরণস্বরূপ, এই এপিএল A←0⋄A⊣{2⊤⍵:1+3×⍵⋄⍵÷2}⍣{⍺=A+←1}⎕। আমি মনে করি যে সম্ভবত এটি সমাধান করার উদ্দেশ্যে করা সমস্যা সম্পর্কে একটি মন্তব্য যোগ্যতা হবে, হুঁ?


2

কোডটি যদি তুচ্ছ হয় তবে এর ব্যাখ্যামূলক মন্তব্যের দরকার নেই। কোডটি যদি তুচ্ছ না হয় তবে ব্যাখ্যামূলক মন্তব্যটি সম্ভবত তুচ্ছ-তুচ্ছ হতে পারে।

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

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

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

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


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

0

এখনও উল্লেখ করা হয়নি এমন একটি বিষয় হ'ল কখনও কখনও কোনও কোডের একটি অংশ কী করে সে সম্পর্কে সঠিকভাবে মন্তব্য করা কোনও ক্ষেত্রে বিশেষত একটি বাক্যকে একাধিক উদ্দেশ্যে ব্যবহার করে এমন ক্ষেত্রে সহায়ক হতে পারে। উদাহরণস্বরূপ, ধরে নিচ্ছি যে সমস্ত ভেরিয়েবল প্রকারভেদযুক্ত float, বিবেচনা করুন:

f1 = (float)(f2+f3); // Force result to be rounded to single precision
f4 = f1-f2;

স্পষ্টভাবে একটি ভোটদান প্রভাব floatথেকে floatএকক স্পষ্টতা বৃত্তাকার করা ফলাফলের বলপূর্বক হয়; মন্তব্যটি এইভাবে কেবল কোড কী করে তা বলে দেখা যেতে পারে। অন্যদিকে, কোডটি এর সাথে তুলনা করুন:

thing.someFloatProperty = (float)(f2*0.1); // Divide by ten

এখানে, কাস্টের উদ্দেশ্য হ'ল নির্ভুলভাবে কম্পিউটিংয়ের সবচেয়ে কার্যকরী পদ্ধতিতে (এফ 2/10) কম্পাইলারকে স্কোয়াং করা থেকে বিরত রাখা [এটি 0.1f দ্বারা গুণিত করার চেয়ে আরও সঠিক, এবং বেশিরভাগ মেশিনে এটি 10.0f দ্বারা বিভক্ত করার চেয়ে দ্রুত]।

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


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

বিশেষত ডিবাগিংয়ের সময় আপনি কখনই ধরে নিতে পারবেন না যে কোনও ভাল কারণেই করা হয়েছে।
gnasher729

@ ডেভিডকে: আমার দ্বিতীয় উদাহরণ কোডের উদ্দেশ্যটি কোডের প্রথম টুকরোটির সাথে বিপরীত ছিল। কোডের দ্বিতীয় অংশে প্রোগ্রামারের উদ্দেশ্য সম্ভবত এটির someFloatPropertyসবচেয়ে সঠিক উপস্থাপনা রাখা উচিত f2/10; দ্বিতীয় কাস্টের প্রাথমিক উদ্দেশ্যটি কেবল কোডটি সংকলন করা । প্রথম উদাহরণে, তবে, অপরিবর্তিত কাজগুলি ইতিমধ্যে কার্যকর হওয়ার কারণে সাধারণত এটির সাধারণ উদ্দেশ্যে (একটি সংকলন-টাইপ টাইপ অন্যটিতে পরিবর্তন করা) প্রয়োজন হয় না float। মন্তব্য পরিষ্কার যে ঢালাই করতে স্থল হয় সেকেন্ডারি উদ্দেশ্য (rounding) জন্য প্রয়োজন ছিল।
ক্যাট

(float)দ্বিতীয় উদাহরণে the ালাই সম্পর্কে আপনার কোনও মন্তব্য করার দরকার নেই এই ধারণার সাথে আমি একমত । প্রশ্নটি আক্ষরিক ধ্রুবক সম্পর্কে 0.1। আপনি ব্যাখ্যা করেছিলেন (পাঠ্যের পরবর্তী অনুচ্ছেদে) কেন আমরা লিখব 0.1: "এটি 0.1f দ্বারা গুণিত করার চেয়ে আরও সঠিক।" আমি পরামর্শ দিচ্ছি যে সেগুলি সেই মন্তব্যে হওয়া উচিত।
ডেভিড কে

@DavidK: আমি মন্তব্য অন্তর্ভুক্ত অবশ্যই যদি আমি জানতাম যে 0.1f অপ্রত্যাশিতভাবে যথাযথ নয় এমন হবে এবং 0.1f ব্যবহার করেন যদি আমি জানতাম যে স্পষ্টতা হারানোর গ্রহণযোগ্য হবে এবং যে 0.1f আসলে বস্তুগত দ্রুত 0.1 চেয়ে হবে । আমি যদি এই দুটি জিনিস সত্যই না জানি, তবে আমার কোডিং অভ্যাসটি অগ্রাধিকার doubleবা অন্তর্বর্তী গণনার জন্য ব্যবহার করা হবে যার মানটি প্রতিনিধিত্বযোগ্য নাও হতে পারে float[যদিও এমন ভাষাগুলিতে যা বিরক্তিকর স্পষ্ট ডাবল টু-ফ্লোট ক্যাসেটগুলির প্রয়োজন, আলস্যতা floatগতির জন্য নয়, বিরক্তি কমানোর জন্য ধ্রুবকগুলির ব্যবহার ব্যবহার করার জন্য চাপ দিতে পারে ]।
সুপারক্যাট

-1

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

আমাদের সাইট ব্যবহার করে, আপনি স্বীকার করেছেন যে আপনি আমাদের কুকি নীতি এবং গোপনীয়তা নীতিটি পড়েছেন এবং বুঝতে পেরেছেন ।
Licensed under cc by-sa 3.0 with attribution required.