হাইপারলিঙ্কযুক্ত, বহিরাগত উত্স কোড ডকুমেন্টেশন [বন্ধ]

Question

উত্স কোডের আমরা এখনও কেন এম্বেড না প্রাকৃতিক ভাষা বিবরণ (অর্থাত, কারণ কেন কোড একটি লাইন লেখা হয়েছিল) সোর্স কোড মধ্যে, বরং একটি পৃথক নথিতে যেমন চেয়ে?

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

এই ধরনের একটি সফ্টওয়্যার বিকাশ ব্যবস্থায় কোন ত্রুটিগুলি বাধা দেবে?

প্রশ্নটি পরিষ্কার করতে সহায়তা করার জন্য একটি মক-আপ:

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

সম্ভাব্য সুবিধার মধ্যে রয়েছে:

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

বিঃদ্রঃ:

• ডকুমেন্টেশন উইন্ডোটি ধসে যেতে পারে
• উত্স ফাইলগুলি দেখতে বা তুলনা করার জন্য কর্মপ্রবাহ প্রভাবিত হবে না
• বাস্তবায়ন কীভাবে ঘটে তা একটি বিশদ; ডকুমেন্টেশন হতে পারে:
  • উত্স ফাইলের শেষে রাখা;
  • কনভেনশন ( filename.c, filename.c.doc) দ্বারা দুটি ফাইলে বিভক্ত ; অথবা
  • সম্পূর্ণ ডাটাবেস চালিত
• হাইপারলিঙ্কযুক্ত ডকুমেন্টেশনের মাধ্যমে, আমি বোঝাতে চাইছি বাহ্যিক উত্সগুলি (যেমন স্ট্যাকওভারফ্লো বা উইকিপিডিয়া) এবং অভ্যন্তরীণ দলিলগুলি (যেমন, সাবডোমেনের একটি উইকি যা ব্যবসায়ের প্রয়োজনীয়তার ডকুমেন্টেশনকে ক্রস-রেফারেন্স করতে পারে) এবং অন্যান্য উত্স ফাইলগুলিতে (জাভাডক্সের মতো) l

সম্পর্কিত থ্রেড: শিল্পে ডকুমেন্টেশনের প্রতিরোধের কী আছে?

Comments

আপনি এই পদ্ধতির মধ্যে কি সুবিধা দেখতে পাচ্ছেন?

— উওও

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

— স্পেসট্রিকার

ইকলিপস আপনাকে ইতিমধ্যে যা দেয় তার থেকে এটি কীভাবে আলাদা? i.stack.imgur.com/HEQ8w.jpg (কার্সারটি কী রয়েছে তার কোড, প্যাগেজ রূপরেখা এবং নীচে প্যানেল জাভডোক)

"স্ফীত মেনু" মন্তব্য কোডের সাথে অন্তর্নির্মিত। এভাবেই আলাদা।

— ডেভ জার্ভিস

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

— ডেভ জারভিস

Answer 1

এই সমস্যাটি আমাকে সর্বদা বিরক্ত করে, এবং আমরা যে দিকটি চেষ্টা করে সমাধান করার চেষ্টা করব সে সম্পর্কে আমি কেবল একটি ধারণা পেয়েছি (আমি কীভাবে এই প্রশ্নটি পেলাম)।

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

প্রথমত, ব্যবহারকারীর ডকুমেন্টেশন থেকে কোড মন্তব্যগুলিকে আলাদা করতে দিন।

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

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

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

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

তাহলে আমরা কেন এটি একই ফাইলটিতে রাখতে চাই? ঠিক আছে, কেউই কোড থেকে তাদের ডকুমেন্টেশন সিঙ্কের বাইরে রাখতে চায় না। তবে আমরা যাইহোক এটি করি, এবং বিশেষত এখন মার্কডাউনের বড় সাফল্যের দিন। যা আমি মনে করি সঠিক পথে, তবে যদি ছোট হয় তবে ওয়াইয়ে সংক্ষিপ্ত।

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

2 ওয়ে বাইন্ডিংয়ের পরিবর্তে আমাদের কী এক উপায় আছে ?. কোডকে নির্দেশ করে ডকুমেন্টেশন। আমাদের বিশেষ কমান্ডগুলির সাথে মার্কডাউন কোড থাকতে পারে:

Some documentation right here that explains the following code:
   @include_file <path/to/some/file>:<line_start>-<line_end>
or
   @include_file <path/to/some/file>
     @starts_with "some regexp or literal text to search"
     @ends_with "another regexp"
or
   @include_file <path/to/some/file>
     @class MyClass
     @method foo
or any combination or way of linking you could imagine

We can even have semantic in the directives:
   @explain_code <path/and/same/of/above>
   @example_code <path/and/same/of/above>
   @performance_notice <path/and/same/of/above>

Which would do basically the same, but it adds the intention of why
do we want to add this code in the first place, which could be 
used different by an IDE. 

এটি কিছু সংযোজন সহ মার্কআপ হওয়ার সুবিধা রয়েছে এবং সঠিক সরঞ্জামগুলির সাহায্যে আমরা এতে আরও মান যুক্ত করতে পারি।

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

Answer 2

404 পৃষ্ঠা খুঁজে পাওয়া যায়নি

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

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

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

Answer 3

আমি যে সম্ভাব্য অসুবিধাগুলি দেখছি:

• আপনার একটি বিশেষ সম্পাদক দরকার যা এই বৈশিষ্ট্যটি কার্যকর করে

• কোডটি কেবল আর সরল পাঠ নয়, ভিসিএস-এস-এ পরিচালনা এবং পরিচালনা করা সহজ

• কোডটি দিয়ে কাজ করতে আপনার আরও দ্বিগুণ স্ক্রিন প্রস্থের প্রয়োজন

আপনার যুক্তি হিসাবে:

আরও সোর্স কোড এবং স্ক্রিনে আরও ডকুমেন্টেশন একবারে

পাশাপাশি আপনি দুটি ফাইল দেখতে চাইলে অসুবিধা হতে পারে।

উত্স কোডের স্বাধীনভাবে ডকুমেন্টেশন সম্পাদনা করার ক্ষমতা (ভাষা নির্বিশেষে?)

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

একত্রিত হওয়া বিরোধগুলি ছাড়াই সমান্তরালে ডকুমেন্টেশন এবং উত্স কোড লিখুন

আবার, সম্ভবত একটি অসুবিধা। যদি আপনার দস্তাবেজগুলি কোডের সাথে গভীরভাবে অন্তর্নিহিত থাকে, তবে আপনি কীভাবে সেগুলি স্বাধীনভাবে সম্পাদনা করতে পারেন?

উচ্চতর পাঠ্য বিন্যাস সহ রিয়েল-টাইম হাইপারলিঙ্কযুক্ত ডকুমেন্টেশন

যদি কোডটিতে থাকে তবে এটি ইতিমধ্যে রিয়েল-টাইম;) হাইপারলিংকের ক্ষেত্রে, সংজ্ঞায় ঝাঁপ দেওয়া বেশিরভাগ আইডিইতে ইতিমধ্যে প্রয়োগ করা হয়েছে।

বিভিন্ন প্রাকৃতিক ভাষায় অর্ধ-রিয়েল-টাইম মেশিনের অনুবাদ

আপনি কেন নিয়মিত মন্তব্য / ডকাস্ট্রিং সহ এটি করতে পারবেন না তা আমি দেখতে পাচ্ছি না।

কোডের প্রতিটি লাইন কোনও টাস্ক, ব্যবসায়ের প্রয়োজনীয়তা ইত্যাদির সাথে স্পষ্টভাবে সংযুক্ত করা যেতে পারে

এটি সম্পর্কে আমি অনিশ্চিত ... নিয়মিত মন্তব্য দিয়ে এটি অর্জন করা যায় না?

কোডের প্রতিটি লাইনটি লেখার সময় ডকুমেন্টেশন স্বয়ংক্রিয়ভাবে টাইমস্ট্যাম্প করতে পারে (মেট্রিক)

ভিসিএস-এস ইতিমধ্যে এই ধরণের তথ্য সরবরাহ করে না?

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

Comments

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

— ডেভ জার্ভিস

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

— ফিজারী

Answer 4

প্রথমত, ডকের মন্তব্যগুলির কোডের সাথে চলতে হবে - এগুলিকে অন্যত্র সরিয়ে নেওয়া কেবল কার্যত শূন্যের জন্য জিনিসগুলি হ্যান্ডেল করা অবিশ্বাস্যরকম কঠিন করে তোলে। তাহলে কেন বিরক্ত!

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

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

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

Answer 5

@ বোগদান ইতিমধ্যে যা বলেছে তা ছাড়াও আমি কয়েকটি যুক্ত করব:

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

• বেশিরভাগ আইডিইগুলি বিচ্ছিন্ন কোড / মন্তব্যগুলিকে সমর্থন করে , শেষ ফলাফলগুলি নিম্নলিখিত হিসাবে:

  স্বাভাবিকের পরিবর্তে:

  

কোডটি আরও পঠনযোগ্য করুন, যদি আপনার মন্তব্যগুলির প্রয়োজন না হয়।

Answer 6

উত্স কোড এবং ডকুমেন্টেশন যেভাবে এটি করা উচিত।

http://jasmine.github.io/2.3/introduction.html