বিদ্যমান কোড বেস ডকুমেন্ট করার জন্য পদ্ধতি

Question

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

আমার প্রশ্নটি হ'ল:

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

কোনও বৃহত অ্যাপ্লিকেশন সঠিকভাবে এবং দ্রুত ডকুমেন্ট করার জন্য আপনি কোন পদ্ধতিটি ব্যবহার করবেন যার কোনও বিদ্যমান ইনলাইন ডকুমেন্টেশন নেই, না বাহ্যিক ডকুমেন্টেশনের ইনলাইন রেফারেন্স রয়েছে?

Comments

+1 এটি কীভাবে পরিচালনা করবেন তা এটি কীভাবে করা যায় তত গুরুত্বপূর্ণ।

আমি দেখেছি বেশিরভাগ কোড নথিভুক্ত নয়। আমি অন্য লোকেদের কোডগুলি পরিষ্কার করার চেষ্টা করেছি এবং এর জন্য চিৎকার পেয়েছি এবং এটি আমার বার্ষিক পর্যালোচনাতে প্রকাশিত হয়েছে। যদি আপনার পৃথিবীর সব সময় থাকে, বা আপনি কীভাবে আপনার 50 টি ঘন্টা ব্যয় করেন সেগুলি তারা খেয়াল করে না, তবে অবশ্যই প্রশ্নটি "আমি এটি কীভাবে করব?" হওয়া উচিত। তবে, আপনি কি নিশ্চিত যে আপনি এটি করতে চান? কোম্পানির সংস্কৃতি, বিক্রয় বাড়ানোর জন্য তারা কতটা মরিয়া, সফ্টওয়্যার ব্যবসা তারা কতটা ভাল বোঝে, ... তারা কোন ভাষা এবং সরঞ্জাম ব্যবহার করে তার উপর অনেক কিছুই নির্ভর করে। সি # এর জন্য স্টাইলকপ এবং ঘোস্টডক নামে একটি নিফটি সরঞ্জাম রয়েছে। সরঞ্জাম বিদ্যমান কিন্তু সময় অভাব।

— কাজ

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

— মার্ক বুথ

Answer 1

লিগ্যাসি কোড-বেসগুলি ডকুমেন্টিং

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

ইন-কোড ডকুমেন্টেশন

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

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

ডকুমেন্টেশন হিসাবে পরীক্ষা

আরেকটি গুরুত্বপূর্ণ বিষয় হ'ল ভাল সংহতকরণ এবং ইউনিট পরীক্ষা করা having

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

একইভাবে, ইউনিট-পরীক্ষাগুলি প্রায়শই বাহ্যিক নির্ভরতাগুলি সুস্পষ্টভাবে নির্দেশ করে যার মাধ্যমে জিনিসগুলি মক এড আউট করা দরকার।

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

উচ্চ স্তরের ডকুমেন্টেশন

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

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

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

Comments

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

— ইরক্যাম

Answer 2

কৌশলী প্রশ্ন. মূলত, আমি "রিফ্যাক্টরিং" পদ্ধতিটি ব্যবহার করতাম, যা আমি "যদি আপনি কোডটি স্পর্শ করেন, ডকুমেন্টটি" হিসাবে পুনঃস্থাপন করবেন।

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

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

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

Comments

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

— ক্যাস্পার ভ্যান ডেন বার্গ

Answer 3

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

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

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

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

Answer 4

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

Answer 5

আমি ডক্সিজেন মন্তব্য ব্যবহার করব। ডক্সিজেনের আরও আউটপুট ফর্ম্যাট রয়েছে যা অন্যান্য ফ্রি ফর্ম্যাটগুলি শেখার জন্য সহজ।

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

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

Answer 6

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

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