Documentation and User Guides (program ကို ရှင်းပြတဲ့ စာရွက်စာတမ်းနဲ့ အသုံးပြုနည်း လမ်းညွှန်များ)

ဘယ်မှာ အသုံးဝင်လဲ: ကိုယ့် software ကို သုံးမယ့်သူတွေ ဒါမှမဟုတ် maintain (နောက်ပိုင်းမှာ ပြင်ဆင်ပြီး update လုပ်) မယ့်သူတွေအတွက် ရေးတဲ့အခါ အသုံးဝင်ပါတယ်၊ လအနည်းငယ် ကြာပြီးနောက်က ကိုယ့်ကိုယ်ကိုယ်လည်း ပါပါတယ်။ IB Computer Science (နိုင်ငံတကာ ကျောင်းတွေမှာ သင်တဲ့ ကွန်ပျူတာသိပ္ပံ သင်ရိုး) ရဲ့ Internal Assessment (IA၊ IB သင်တန်းမှာ ကျောင်းသားတစ်ယောက်ချင်း ကိုယ်တိုင် တည်ဆောက်ရပြီး ကျောင်းက ဆရာက အမှတ်ပေးတဲ့ အပိုင်း) မှာ Criterion D: Development (အမှတ်ပေး စံနှုန်း D: product တည်ဆောက်ခြင်း) က ကိုယ် တင်ပြတဲ့ code မှန်သမျှ “must include relevant comments, be consistent and be readable” (သက်ဆိုင်တဲ့ comment တွေ၊ ဆိုလိုတာက code ထဲမှာ ရေးထားတဲ့ ရှင်းပြချက်တွေ ပါရမယ်၊ တစ်ပုံစံတည်း ဖြစ်ရမယ်၊ ဖတ်ရလွယ်ရမယ်) လို့ ဆိုပါတယ်။ IB coursework (သင်တန်းကာလအတွင်း လုပ်ပြီး တင်ရတဲ့ အလုပ်) အားလုံးလိုပဲ IA မှာလည်း ကိုယ်သုံးတဲ့ ရင်းမြစ်တိုင်းကို acknowledge (ဘယ်က ရလာလဲ ဖော်ပြ) လုပ်ဖို့ လိုပါတယ်၊ ဆိုလိုတာက တခြားသူတွေရဲ့ အလုပ် တစ်ခုချင်းစီ ဘယ်ကနေ ရလာလဲ ဆိုတာကို ပြောပြရမယ်ပါ။ IA က user guide (အသုံးပြုနည်း လမ်းညွှန်) ဒါမှမဟုတ် README (project အကြောင်း ပထမဆုံး ဖတ်ရမယ့် file) ကို မတောင်းပါဘူး။ ဒါပေမယ့် ကိုယ့် အလုပ်ကို အရင်က မမြင်ဖူးတဲ့ စာဖတ်သူ တစ်ယောက်အတွက် ရေးဖို့ တောင်းပါတယ်: ကိုယ့် Criterion C: System overview (အမှတ်ပေး စံနှုန်း C: စနစ်ရဲ့ ခြုံငုံ ဖော်ပြချက်) က တခြားသူ တစ်ယောက်က ကိုယ့် product (IA အတွက် ကိုယ်တိုင် တည်ဆောက်ရတဲ့ program ဒါမှမဟုတ် app) ကို ပြန်တည်ဆောက်နိုင်လောက်အောင် ရှင်းလင်းရပါမယ်။ ဒီအလေ့အထတွေက ဘယ် software project မှာမဆို အသုံးဝင်ပါတယ်။

မာတိကာ

ခြုံငုံ မိတ်ဆက်
Documentation အမျိုးအစားများ
User Guide ရေးခြင်း
Technical Documentation (developer တွေအတွက် နည်းပညာပိုင်း ရှင်းပြချက်)
စာဖတ်သူကို အထောက်အကူ ဖြစ်တဲ့ Code Comment များ
1. နာမည်ပေးခြင်းနဲ့ တစ်ပုံစံတည်း ဖြစ်ခြင်း
README: Project တစ်ခုရဲ့ ရှေ့တံခါး
ရိုးသားမှု: ကိုယ်သုံးတဲ့ ရင်းမြစ်တွေကို ကိုးကား ဖော်ပြခြင်း
Quick Check (အမြန် စစ်ဆေးမေးခွန်း)
Document အမျိုးအစား တွဲဖက်ခြင်း
Practice Exercises (လေ့ကျင့်ခန်းများ)
ဆက်စပ် ခေါင်းစဉ်များ

ခြုံငုံ မိတ်ဆက်

Code ကို ရေးတာထက် ဖတ်တာက အကြိမ်ရေ အများကြီး ပိုများလေ့ ရှိပါတယ်။ Project တစ်ခု ပြီးပြီး လအနည်းငယ် ကြာတဲ့အခါ အဲဒါ ဘာကြောင့် အခုလို အလုပ်လုပ်လဲ ဆိုတာကို ကိုယ်တိုင် မမှတ်မိတော့တာ ဖြစ်နိုင်ပြီး တခြားသူ ဘယ်သူမဆိုကတော့ အဲဒီ အသိ မပါဘဲ စရပါတယ်။ Documentation (program ကို ရှင်းပြတဲ့ စာရွက်စာတမ်း၊ ဆိုလိုတာက program ကို သုံးတဲ့သူ ဒါမှမဟုတ် အဲဒီ program ပေါ်မှာ အလုပ်လုပ်တဲ့သူတွေအတွက် ရေးထားတဲ့ ရှင်းပြချက်) က user (အသုံးပြုသူ) တွေကို software သုံးတတ်အောင် ကူညီပြီး developer (software ရေးသူ) တွေ (အနာဂတ်က ကိုယ်ကိုယ်တိုင်လည်း ပါပါတယ်) ကို software ကို maintain လုပ်နိုင်အောင် ကူညီပါတယ်။ Code တစ်ခုတည်းကနေ ရှာဖွေ နားလည်ဖို့ ခက်နိုင်တဲ့ ညွှန်ကြားချက်တွေ၊ setup (စတင် ပြင်ဆင်ခြင်း) အဆင့်တွေနဲ့ ဒီဇိုင်း ဆုံးဖြတ်ချက်တွေကို မှတ်တမ်းတင်ထားပါတယ်။

ကောင်းတဲ့ documentation ဆိုတာ များများ ရေးတာ မဟုတ်ဘဲ သတ်မှတ်ထားတဲ့ စာဖတ်သူ တစ်ယောက်အတွက် မှန်ကန်တဲ့ အကြောင်းအရာတွေကို ရေးတာပါ။ User တွေက သူတို့ လုပ်ချင်တဲ့ အလုပ်တွေအတွက် ညွှန်ကြားချက်တွေ လိုပြီး software ကို maintain လုပ်တဲ့ developer တွေက setup အသေးစိတ်တွေနဲ့ အဓိက ဒီဇိုင်း ရွေးချယ်မှုတွေရဲ့ နောက်က အကြောင်းရင်းတွေ လိုပါတယ်။

Documentation အမျိုးအစားများ

စာဖတ်သူ မတူရင် လိုအပ်တဲ့ စာရွက်စာတမ်းလည်း မတူပါဘူး။ ဒီစာမျက်နှာမှာ အသုံးများတဲ့ အမျိုးအစား လေးမျိုးကို ဖော်ပြထားပါတယ်။

အမျိုးအစား	ဘယ်သူ့အတွက်လဲ	ဘာမေးခွန်းကို ဖြေပေးလဲ
User guide	Software ကို သုံးနေတဲ့သူ	“ကိုယ်လုပ်ချင်တဲ့ အလုပ်ကို ဘယ်လို လုပ်ရမလဲ။”
Technical documentation (software ကို ပြင်ဆင်မယ့် developer တွေအတွက် နည်းပညာပိုင်း ရှင်းပြချက်)	Software ကို maintain လုပ်နေတဲ့ developer	“ဒါ ဘယ်လို အလုပ်လုပ်လဲ၊ ဘယ်လို setup လုပ်ပြီး ဘယ်လို ပြင်ရမလဲ။”
Code comments (code ထဲမှာ ရေးထားတဲ့ ရှင်းပြချက်များ)	Code ကို နောက်ထပ် ဖတ်မယ့် ဘယ်သူမဆို	“Code ရဲ့ ဒီအပိုင်းက ဘာကြောင့် ဒီလို လုပ်တာလဲ။”
README	Project ကို ဖွင့်ကြည့်တဲ့ ဘယ်သူမဆို	“ဒါ ဘာလဲ၊ ဘယ်လို စရမလဲ။”

User guide ကို user manual (အသုံးပြုသူ လက်စွဲ) ဒါမှမဟုတ် user documentation (အသုံးပြုသူအတွက် စာရွက်စာတမ်း) လို့လည်း ခေါ်ပါတယ်။ အဖြစ်များတဲ့ အမှားက အမျိုးအစားတွေကို ရောထွေးတာပါ: user အတွက် ညွှန်ကြားချက်တွေကို code comment တွေထဲ ထည့်တာ ဒါမှမဟုတ် နည်းပညာ မကျွမ်းကျင်တဲ့ user အတွက် ရည်ရွယ်တဲ့ လမ်းညွှန်ထဲကို နည်းပညာ အသေးစိတ်တွေ ထည့်တာမျိုးပါ။ Code comment တွေက code ကို ဘာကြောင့် အဲဒီလို ရေးခဲ့လဲ ဆိုတာ developer တွေကို ရှင်းပြပါတယ်၊ user guide က software နဲ့ အလုပ်တွေကို ဘယ်လို ပြီးမြောက်အောင် လုပ်ရမလဲ ရှင်းပြပါတယ်။

User Guide ရေးခြင်း

User guide က လူတစ်ယောက်ကို သူ့ အလုပ် ပြီးအောင် software ကို သုံးတတ် အောင် သင်ပေးပါတယ်။ Programmer (program ရေးသူ) အတွက် မဟုတ်ဘဲ user အတွက် ရေးတာ ဖြစ်လို့:

Feature (program ရဲ့ လုပ်ဆောင်ချက်) တွေအလိုက် မဟုတ်ဘဲ task (user လုပ်ချင်တဲ့ အလုပ်) တွေအလိုက် စီပါ။ အပိုင်း တစ်ခုစီကို screen ဒါမှမဟုတ် menu (“ငွေပေးချေမှု Screen”) ရဲ့ နာမည် မဟုတ်ဘဲ user လုပ်ချင်တဲ့ အလုပ်ကို ဖော်ပြတဲ့ ခေါင်းစဉ် (“ငွေပေးချေမှု တစ်ခုကို မှတ်တမ်းတင်နည်း”) ပေးပါ။
ရိုးရှင်းတဲ့ စကားကို သုံးပါ။ User အများစုက “boolean” (true ဒါမှမဟုတ် false တန်ဖိုးပဲ ယူတဲ့ ဒေတာ အမျိုးအစား) ဒါမှမဟုတ် “query” (database ထဲက ဒေတာကို ရှာ၊ ပြင်ဖို့ ပေးတဲ့ အမိန့်) ဆိုတာ ဘာလဲ မသိကြပါဘူး၊ သိဖို့လည်း မလိုသင့်ပါဘူး။ Screen ပေါ်က label (စာတန်း) တွေမှာ ပါတဲ့ စကားလုံးတွေအတိုင်း သုံးပါ။
အဆင့်တွေကို ပြပါ။ နံပါတ်တပ်ထားတဲ့ အဆင့်တွေနဲ့ screenshot (screen ပေါ်က မြင်ကွင်းကို ရိုက်ယူထားတဲ့ ပုံ) တွေက စာပိုဒ်တွေထက် လိုက်လုပ်ရ ပိုလွယ်လေ့ ရှိပါတယ်။ “Add ကို click နှိပ်ပါ၊ ပမာဏကို ရိုက်ထည့်ပါ၊ Save ကို နှိပ်ပါ” ဆိုတာက user ကို ဘာလုပ်ရမလဲ အတိအကျ ပြောပြပါတယ်။
တစ်ခုခု မှားသွားရင် ဘာလုပ်ရမလဲ ပြောပြပါ။ အဖြစ်များတဲ့ ပြဿနာတွေကို ဖြေရှင်းဖို့ ကူညီပေးတဲ့ troubleshooting (ပြဿနာ ရှာဖွေ ဖြေရှင်းခြင်း) အပိုင်း တိုတိုလေး (“စုစုပေါင်း မှားနေပုံ ရရင် … ကို စစ်ကြည့်ပါ”) ပါရင် user က အကူအညီ မတောင်းဘဲ ပြဿနာကို သူ့ဘာသာ ဖြေရှင်းနိုင်တာ များပါတယ်။

User guide တစ်ခုထဲက ကောက်နုတ်ချက် တိုတိုလေး:

ငွေပေးချေမှု တစ်ခုကို မှတ်တမ်းတင်ခြင်း

Main screen (ပင်မ screen) မှာ Add Payment ကို နှိပ်ပါ။

စာရင်းထဲကနေ ကျောင်းသားရဲ့ နာမည်ကို ရွေးပါ။

ပမာဏကို ရိုက်ထည့်ပြီး Save ကို နှိပ်ပါ။ ကျောင်းသားရဲ့ စုစုပေါင်းက ချက်ချင်း update ဖြစ်သွားပါတယ်။

ကျောင်းသားက စာရင်းထဲမှာ မရှိရင် Manage Students ကနေ အရင် ထည့်ပါ။

Code ဘယ်လို အလုပ်လုပ်လဲ ဆိုတာ တစ်လုံးမှ မပါတာကို သတိထားကြည့်ပါ။ ဒီစာဖတ်သူအတွက် အဲဒါက မှန်ကန်ပါတယ်။

Technical Documentation (developer တွေအတွက် နည်းပညာပိုင်း ရှင်းပြချက်)

Technical documentation ကို software ကို maintain လုပ်မယ့် ဒါမှမဟုတ် အသစ်တွေ ထပ်ထည့်မယ့် developer တွေအတွက် ရေးပါတယ်။ အဲဒီ developer တွေထဲမှာ တစ်နှစ်လောက် ကြာပြီးနောက်က ကိုယ်ကိုယ်တိုင် ပါနိုင်ပါတယ်။ System ကို ဘယ်လို ပေါင်းစပ် တည်ဆောက်ထားလဲ ရှင်းပြတာ ဖြစ်လို့ တစ်ယောက်ယောက်က အန္တရာယ်ကင်းကင်း ပြင်နိုင်ပါတယ်။ များသောအားဖြင့် ဒါတွေ ပါပါတယ်:

Setup လုပ်နည်း: program က ဘာတွေ လိုလဲ ဆိုတာပါ၊ ဥပမာ programming language ရဲ့ သတ်မှတ်ထားတဲ့ version တစ်ခု၊ database (ဒေတာ သိမ်းဆည်းတဲ့ စနစ်) တစ်ခု ဒါမှမဟုတ် library (အသင့်ရေးထားတဲ့ code အစု) တွေ၊ ပြီးတော့ ကွန်ပျူတာ အသစ် တစ်လုံးပေါ်မှာ run လို့ရအောင် လုပ်ရမယ့် အဆင့်တွေပါ။ Library ဆိုတာ တခြားသူတွေ ရေးထားပြီး program တစ်ခုက ယူသုံးတဲ့ အသင့်ရေးထားတဲ့ code ပါ။
ဘယ်လို ဒီဇိုင်းလုပ်ထားလဲ: အဓိက အပိုင်းတွေနဲ့ အဲဒါတွေ ဘယ်လို ချိတ်ဆက်ထားလဲ ဆိုတာပါ၊ class diagram (class တွေနဲ့ သူတို့ကြား ဆက်နွယ်မှုကို ပြတဲ့ ပုံ) ဒါမှမဟုတ် data flow diagram (system ထဲမှာ ဒေတာ စီးဆင်းပုံကို ပြတဲ့ ပုံ) လို diagram (ပုံ) တွေနဲ့ ပြလေ့ ရှိပါတယ်။ Program က သိမ်းတဲ့ ဒေတာကိုလည်း ဖော်ပြပါတယ်၊ အဲဒါကို data dictionary ထဲမှာ စာရင်းပြုစုလေ့ ရှိပါတယ်: data dictionary ဆိုတာ ဒေတာ item တစ်ခုချင်းစီကို ဖော်ပြတဲ့ ဇယားပါ (Design Representations (ဒီဇိုင်းကို ဖော်ပြတဲ့ နည်းလမ်းများ) ကို ကြည့်ပါ)။
ဘာကြောင့် ဒီလို တည်ဆောက်ထားလဲ: program ကို ပြင်တဲ့သူက မသိရင် ပြန်ဖျက်မိနိုင်တဲ့ ဆုံးဖြတ်ချက်တွေပါ၊ ဥပမာ ရလဒ်တွေကို database ထဲ မသိမ်းဘဲ file ထဲမှာ ဘာကြောင့် သိမ်းလဲ ဆိုတာမျိုးပါ။
Test လုပ်နည်း: test (program မှန်မမှန် စမ်းစစ်တဲ့ စစ်ဆေးချက်) တွေကို ဘယ်လို run ရမလဲ၊ အဲဒါတွေက ဘာကို စစ်လဲ ဆိုတာပါ (Testing Strategy (စမ်းသပ်ပုံ အစီအစဉ်) ကို ကြည့်ပါ)။
မပြီးသေးတာတွေ: သိထားပြီးသား ပြဿနာတွေနဲ့ ကန့်သတ်ချက်တွေ။

User guide က software ကို ဘယ်လို သုံးရမလဲ ပြောပြပြီး technical documentation က software ဘယ်လို အလုပ်လုပ်လဲ၊ ဘယ်လို ပြင်ရမလဲ ပြောပြပါတယ်။

စာဖတ်သူကို အထောက်အကူ ဖြစ်တဲ့ Code Comment များ

Code comment တွေဆိုတာ code ကို နောက်ထပ် ဖတ်မယ့်သူအတွက် code ထဲမှာ ရေးထားတဲ့ မှတ်စုတွေပါ။ ကွန်ပျူတာက program ကို run တဲ့အခါ comment တွေကို လျစ်လျူရှုပါတယ်။ အသုံးဝင်တဲ့ စည်းမျဉ်း တစ်ခုက comment the WHY, not the WHAT (code က ဘာ လုပ်လဲ မဟုတ်ဘဲ ဘာကြောင့် လုပ်လဲ ဆိုတာကို comment ရေးပါ) ပါ: ဆုံးဖြတ်ချက် တစ်ခုရဲ့ အကြောင်းရင်းကို ရှင်းပြပါ ဒါမှမဟုတ် ထင်ရှား မနေတဲ့ အပြုအမူကို ရှင်းလင်းပေးပါ။ အောက်က line (code စာကြောင်း) က ပြောပြီးသား အရာကို ထပ်ပြောရုံပဲ ဖြစ်တဲ့ comment တွေကို ရှောင်ပါ။

ဒီမှာ ဥပမာတွေက Java နဲ့ ဖြစ်ပြီး Java မှာ comment က // နဲ့ စပါတယ်။ Python မှာတော့ comment က # နဲ့ စပြီး အကြံပြုချက် အတူတူပဲ သက်ဆိုင်ပါတယ်။

Comment	အကဲဖြတ်ချက်
`count = count + 1; // add one to count`	အသုံးမဝင်ပါ (comment က “count ကို တစ် ပေါင်းပါ” လို့ ဆိုပါတယ်)။ Code က ဒါကို ပြောပြီးသားပါ။
`int maxLength = 32; // the receipt printer fits 32 characters per line`	အသုံးဝင်ပါတယ် (comment က “ပြေစာ printer က line တစ်ကြောင်းမှာ character 32 လုံး ဆံ့တယ်” လို့ ဆိုပါတယ်)။ တန်ဖိုး ဘယ်ကနေ လာလဲ ဆိုတာကို မှတ်တမ်းတင်ထားပါတယ်။
`month = month - 1; // the array of month names starts at index 0`	အသုံးဝင်ပါတယ် (comment က “လ နာမည်တွေ ပါတဲ့ array (အရွယ်အစား ပုံသေ၊ အမျိုးအစားတူ ဒေတာစု) က index (နေရာအမှတ်) 0 ကနေ စတယ်” လို့ ဆိုပါတယ်)။ အမှားလို့ ထင်ရနိုင်တဲ့ အဆင့် တစ်ခုကို ရှင်းပြထားပါတယ်။

ကောင်းတဲ့ comment တွေက code တစ်ခုတည်းကို ကြည့်ပြီး စာဖတ်သူ မသိနိုင်တာတွေကို ရှင်းပြပါတယ်: ရွေးချယ်မှု တစ်ခုရဲ့ နောက်က အကြောင်းရင်း၊ code က ကိုင်တွယ်ရမယ့် ပုံမှန် မဟုတ်တဲ့ အခြေအနေ (ဥပမာ list (ဒေတာ စာရင်း) အလွတ်)၊ တန်ဖိုး တစ်ခု ဘယ်ကနေ လာလဲ ဒါမှမဟုတ် မှားနေပုံ ရပေမယ့် တမင် လုပ်ထားတဲ့ အရာ တစ်ခုအကြောင်း သတိပေးချက်တို့ပါ။ Comment တစ်ခုက သူ့အောက်က line ကို ထပ်ပြောရုံပဲ ဆိုရင် ဖျက်ပစ်ပါ။

ရေးသင့်တဲ့ WHAT comment အမျိုးအစား တစ်ခု ရှိပါတယ်: method (သီးခြား အလုပ်တစ်ခု လုပ်ပေးတဲ့ code အပိုင်း) တစ်ခု ဒါမှမဟုတ် code block (code အစု) တစ်ခုရဲ့ အပေါ်မှာ ရေးတဲ့ အကျဉ်းချုပ် တိုတိုပါ။ အဲဒါက တစ်ခုလုံးအနေနဲ့ ဘာလုပ်လဲ၊ ဘာတွေ လိုလဲ၊ ဘာကို ပြန်ပေးလဲ ဆိုတာကို ပြောပြပါတယ်။ Method ဆိုတာ အလုပ် တစ်ခု လုပ်တဲ့ နာမည်ပေးထားတဲ့ code block တစ်ခုပါ၊ Python မှာ function လို့ မကြာခဏ ခေါ်ပါတယ်။ အပေါ်မှာ အကျဉ်းချုပ် ပါရင် စာဖတ်သူက method ရဲ့ line တိုင်းကို မဖတ်ဘဲ သုံးနိုင်ပါတယ်။ Java မှာ ဒီလို အကျဉ်းချုပ်တွေကို /** နဲ့ စတဲ့ Javadoc comment (method တစ်ခုစီကို ဖော်ပြတဲ့ Java ရဲ့ အထူး comment) တွေအဖြစ် ရေးလေ့ ရှိပါတယ်။ javadoc လို့ ခေါ်တဲ့ tool တစ်ခုက အဲဒီ comment တွေကို method တစ်ခုစီကို ဖော်ပြတဲ့ web page တွေအဖြစ် ပြောင်းပေးနိုင်ပါတယ်။ Python မှာတော့ အဲဒီ အလုပ်အတွက် docstring (function ရဲ့ အစမှာ ရေးတဲ့ ရှင်းပြချက် စာသား) ကို သုံးပါတယ်: function တစ်ခုထဲမှာ ပထမဆုံး statement (code ထဲက ညွှန်ကြားချက်) အဖြစ် ထည့်ထားတဲ့ quotation mark (မျက်တောင်အဖွင့်အပိတ်) တွေကြားက စာသားပါ။ Line တစ်ကြောင်းထက် ပိုရှည်လို့ ရပါတယ်။

Comment တစ်ခုကို အမြန် စစ်နည်း: အဲဒီ comment ကို ဖျက်လိုက်ရင် နောက် စာဖတ်သူက code ကနေ အလွယ်တကူ မရနိုင်တဲ့ အချက်အလက်ကို ဆုံးရှုံးမလား။ ဆုံးရှုံးမယ်ဆိုရင် ထားပါ။ မဆုံးရှုံးဘူးဆိုရင် အဲဒီ comment က ရှုပ်ပွမှု သက်သက် ဖြစ်ပြီး ရှုပ်ပွမှုက အသုံးဝင်တဲ့ comment တွေကို မြင်ရ ခက်စေပါတယ်။

နာမည်ပေးခြင်းနဲ့ တစ်ပုံစံတည်း ဖြစ်ခြင်း

Code ကို ဖတ်ရလွယ်အောင် လုပ်ပေးတဲ့ အရာတွေထဲမှာ comment က တစ်စိတ်တစ်ပိုင်းပဲ ပါပါတယ်။ ရှင်းလင်းတဲ့ နာမည်တွေကလည်း ရှင်းပြတဲ့ အလုပ် အများကြီးကို လုပ်ပေးပါတယ်။ Variable (တန်ဖိုး သိမ်းထားတဲ့ နာမည်ပေးထားတဲ့ နေရာ) တွေ၊ method တွေနဲ့ class (object တွေ ဖန်တီးဖို့ ပုံစံခွက်) တွေအတွက် ကိုယ်ရွေးတဲ့ နာမည်တွေကို identifier (variable၊ method၊ class တို့ကို ပေးတဲ့ နာမည်) လို့ ခေါ်ပါတယ်: identifier minutesLeft (ကျန်တဲ့ မိနစ်) က variable ထဲမှာ ဘာ သိမ်းထားလဲ စာဖတ်သူကို ပြောပြပေမယ့် m ကတော့ မပြောပြပါဘူး။ တစ်ပုံစံတည်း ဖြစ်တဲ့ style (ရေးဟန်၊ ဆိုလိုတာက အစအဆုံး တူညီတဲ့ နာမည်ပေးပုံ၊ indentation (စာကြောင်းရှေ့က ကွက်လပ်) နဲ့ layout (စီစဉ်ပုံ)) က အဓိပ္ပာယ် မရှိတဲ့ ကွာခြားချက်တွေကြောင့် စာဖတ်သူ အာရုံ မပြောင်းအောင် လုပ်ပေးပါတယ်။ Language တစ်ခုစီမှာ naming convention (နာမည်ပေးတဲ့ ရေးထုံး) ရှိပါတယ်၊ ဆိုလိုတာက နာမည်တွေကို ရေးဖို့ သဘောတူထားတဲ့ နည်းလမ်းပါ: Java မှာ variable နာမည်တွေကို camelCase (minutesLeft၊ ပထမ စကားလုံးကလွဲပြီး စကားလုံးတိုင်းကို စာလုံးကြီးနဲ့ စတဲ့ ရေးပုံ) နဲ့ ရေးလေ့ ရှိပြီး Python မှာ snake_case (minutes_left၊ စကားလုံးတွေကို underscore နဲ့ ဆက်ပြီး စာလုံးသေးနဲ့ ရေးပုံ) နဲ့ ရေးလေ့ ရှိပါတယ်။ ကိုယ့် language ရဲ့ ပုံမှန် convention ကို သုံးပြီး အစအဆုံး လိုက်နာပါ။

IB CS သင်တန်း တက်နေသူတွေအတွက် မှတ်ချက်: Internal Assessment မှာ comment တွေ၊ တစ်ပုံစံတည်း ဖြစ်မှုနဲ့ ဖတ်ရလွယ်မှုအကြောင်း Criterion D ဆိုထားတာက ကိုယ်တင်ပြတဲ့ code မှန်သမျှအတွက် သက်ဆိုင်ပါတယ်၊ ကိုယ့် documentation (IA အတွက် တင်ရတဲ့ ရေးသားချက်) ထဲက excerpt (ကောက်နုတ်ပြထားတဲ့ code အပိုင်း) တွေလည်း ပါပါတယ်။ Excerpt တစ်ခုစီက ကိုယ့် appendix (နောက်ဆက်တွဲ၊ documentation နဲ့အတူ တင်တဲ့ အပို အကြောင်းအရာ) ထဲက source code (programmer ရေးထားတဲ့ မူရင်း code) အပြည့်အစုံရဲ့ ဘယ်နေရာကလဲ ဆိုတာ ကိုးကား ဖော်ပြရပါမယ်။ Documentation ရဲ့ စကားလုံး 2,000 ကန့်သတ်ချက်ထဲမှာ code excerpt တွေ၊ comment တွေနဲ့ diagram တွေ မပါပါဘူး။

README: Project တစ်ခုရဲ့ ရှေ့တံခါး

README ဆိုတာ project တစ်ခုကို မိတ်ဆက်ပေးတဲ့ file တစ်ခုပါ။ လူတွေ ပထမဆုံး ဖွင့်ကြည့်တဲ့ file ဖြစ်လေ့ ရှိပြီး README.md ဒါမှမဟုတ် README.txt လို့ နာမည်ပေးလေ့ ရှိပါတယ်။ ကောင်းတဲ့ README က တိုပြီး မေးခွန်း အနည်းငယ်ကို မြန်မြန် ဖြေပေးပါတယ်:

ဒါ ဘာလဲ။ စာကြောင်း တစ်ကြောင်း နှစ်ကြောင်း။
ဘာလုပ်ပေးလဲ။ အဓိက feature တွေ။
ဘယ်လို run ရမလဲ။ အလုပ်လုပ်အောင် လုပ်ရမယ့် အဆင့်တွေ၊ သူ မှီခိုနေရတဲ့ အရာ မှန်သမျှ အပါအဝင်။
ဘယ်လို သုံးရမလဲ။ အခြေခံတွေ ဒါမှမဟုတ် user guide ဆီ link တစ်ခု။
ဘယ်သူ လုပ်ခဲ့တာလဲ၊ တခြားသူတွေ ဘာကို ပြန်သုံးလို့ ရလဲ။ ရေးသားသူနဲ့ licence (code ကို တခြားသူတွေ ဘာလုပ်ခွင့် ရှိလဲ သတ်မှတ်ထားတဲ့ စည်းကမ်းချက်)။

README က အတိုချုပ်ကို ပေးပါတယ်၊ ပိုပြည့်စုံတဲ့ setup နဲ့ ဒီဇိုင်း အသေးစိတ်တွေက technical documentation ထဲမှာ ရှိသင့်ပါတယ်။ ရှင်းလင်းတဲ့ README တစ်ခုက project ကို အသစ် တွေ့တဲ့သူ နားလည်ဖို့နဲ့ run ဖို့ ပိုလွယ်စေနိုင်ပါတယ်။ README မရှိရင် စရတာ ပိုခက်နိုင်ပါတယ်: code ဘယ်လောက်ပဲ ကောင်းကောင်း project က ဘာလဲ၊ ဘယ်လို run ရမလဲ ဆိုတာကို စာဖတ်သူက ခန့်မှန်းရနိုင်ပါတယ်။

ရိုးသားမှု: ကိုယ်သုံးတဲ့ ရင်းမြစ်တွေကို ကိုးကား ဖော်ပြခြင်း

တခြားသူတွေရဲ့ အလုပ်ကို သုံးတာက ပုံမှန်ဖြစ်ပြီး ယုတ္တိရှိတာ များပါတယ်။ ဒါပေမယ့် အဲဒါကို ကိုယ့်အလုပ်အဖြစ် တင်ပြတာကတော့ ပုံမှန်လည်း မဟုတ်၊ သင့်တော်လည်း မသင့်တော်ပါဘူး။ Library တစ်ခုကို သုံးခဲ့ရင်၊ tutorial (အဆင့်ဆင့် သင်ပြတဲ့ လမ်းညွှန်) တစ်ခုကို လိုက်လုပ်ခဲ့ရင် ဒါမှမဟုတ် online မှာ တွေ့တဲ့ code ကို ပြင်ပြီး သုံးခဲ့ရင် အဲဒါကို ဖော်ပြပါ: code ဘေးက comment ထဲမှာရော ကိုယ့် documentation ထဲမှာပါ ဖော်ပြပါ။ တစ်ခုခု ဘယ်ကနေ လာလဲ ဆိုတာကို ပြောတာကို ရင်းမြစ်ကို citing (ကိုးကားခြင်း) ဒါမှမဟုတ် acknowledging (အသိအမှတ်ပြု ဖော်ပြခြင်း) လို့ ခေါ်ပါတယ်။

AI (ဉာဏ်ရည်တု) tool တွေအတွက်လည်း အတူတူပါပဲ။ AI tool တစ်ခုက ကိုယ်သုံးတဲ့ code ဒါမှမဟုတ် စာသားကို ရေးပေးခဲ့ရင် ဒါမှမဟုတ် ပြင်ပေးခဲ့ရင် ဘယ် tool ကို သုံးခဲ့လဲ၊ အဲဒါကို ဘာမေးခဲ့လဲ (ကိုယ့် prompt၊ ဆိုလိုတာက AI ကို ဘာလုပ်ရမလဲ စာနဲ့ ပြောတဲ့ ညွှန်ကြားချက်)၊ ဘယ်အချိန်မှာလဲ၊ ဘာထုတ်ပေးခဲ့လဲ ဆိုတာကို ဖော်ပြပါ။ သုံးခဲ့တာကို ဖော်ပြရုံနဲ့ သုံးပုံ တိုင်းကို လက်ခံနိုင်တယ်လို့ မဆိုလိုပါဘူး။ ဒါကြောင့် အမှတ်ပေး စစ်ဆေးမယ့် အလုပ်အတွက် AI tool ကို မသုံးခင် ကိုယ့် ကျောင်းရဲ့ စည်းကမ်းတွေကို စစ်ကြည့်ပြီး ဆရာကို မေးပါ။

ဒါက အကြောင်း သုံးချက်ကြောင့် အရေးကြီးပါတယ်:

Academic honesty (ပညာရေးဆိုင်ရာ ရိုးသားမှု)။ တခြားသူရဲ့ code ကို ကိုယ့် code လို တင်ပြတာက plagiarism (သူများ အလုပ်ကို ကိုယ့်အလုပ်လို တင်ပြခြင်း) ပါ။ ဖော်ပြထားရင် ဘယ်အပိုင်းတွေက ကိုယ့် ကိုယ်ပိုင် အလုပ်လဲ ဆိုတာ ရှင်းလင်းစေပါတယ်။
Licensing (licence ဆိုင်ရာ ခွင့်ပြုချက်)။ Online မှာ တွေ့တဲ့ code ကို များသောအားဖြင့် copyright (မူပိုင်ခွင့်) က ကာကွယ်ထားပါတယ်: copyright ဆိုတာ code ကို ပိုင်တဲ့သူ (များသောအားဖြင့် ရေးသားသူ) က ဘယ်သူ ကူးယူခွင့် ရှိလဲ ဆုံးဖြတ်ခွင့် ပေးတဲ့ ဥပဒေပါ။ Code မှာ licence ရှိရင် အဲဒီ licence က ကိုယ် ဘာလုပ်ခွင့် ရှိလဲ ဖော်ပြပါတယ်။ Open-source (ဘယ်သူမဆို ဖတ်၊ သုံး၊ ပြင်ခွင့် ရှိအောင် မျှဝေထားတဲ့) code ကို ဘယ်သူမဆို သူ့ licence ရဲ့ စည်းကမ်းချက်တွေအတိုင်း ဖတ်၊ သုံး၊ ပြင်နိုင်အောင် မျှဝေထားပါတယ်။ Open-source licence တော်တော်များများက ရေးသားသူရဲ့ copyright notice (မူပိုင်ခွင့် ကြေညာချက်) နဲ့ licence စာသားကို code နဲ့အတူ ထားသရွေ့ code ကို ပြန်သုံးခွင့် ပေးပါတယ်။ Licence မပါတဲ့ code က ကိုယ့်ကို ပြန်သုံးခွင့် မပေးပါဘူး၊ ဒါကြောင့် ရေးသားသူကို မေးကြည့်ပါ ဒါမှမဟုတ် တခြား ရင်းမြစ် ရှာပါ။ Licence က ရေးသားသူကို credit (အသိအမှတ်ပြု ဖော်ပြချက်) ပေးဖို့ မတောင်းရင်တောင် academic honesty က တောင်းပါတယ်။
Maintainability (ပြင်ဆင် ထိန်းသိမ်းရလွယ်ခြင်း)။ Program တစ်ခုကို နောက်ပိုင်းမှာ ပြင်ရတာ၊ ပြောင်းရတာ ဘယ်လောက် လွယ်လဲ ဆိုတာပါ။ Code အပိုင်း တစ်ခုက သတ်မှတ်ထားတဲ့ library ဒါမှမဟုတ် tutorial တစ်ခုကနေ လာတာကို သိတဲ့ နောင် စာဖတ်သူက အဲဒီ အပိုင်းကို ပြင်ဖို့ လိုတဲ့အခါ မူရင်းကို ဖတ်ကြည့်နိုင်ပါတယ်။

ဘာတွေ မှတ်တမ်းတင်ရမလဲ။ Library တစ်ခုအတွက်: သူ့နာမည်၊ version၊ ဘယ်ကနေ ရလာလဲ နဲ့ သူ့ licence ကို ကိုယ့် README ဒါမှမဟုတ် documentation ထဲမှာ ရေးပါ၊ ပြီးတော့ ကိုယ့် list of references (ကိုးကားစာရင်း) ထဲမှာ entry (စာရင်းဝင် အချက်) တစ်ခု ထည့်ပါ။ ကိုယ် ပြင်ပြီး သုံးခဲ့တဲ့ code အတွက်: သုံးတဲ့ နေရာမှာ comment တစ်ခု ရေးပြီး ဘယ်ကနေ ရလာလဲ၊ ကိုယ် ဘာတွေ ပြင်ခဲ့လဲ ဖော်ပြပါ၊ ပြီးတော့ ကိုယ့် list of references (ကိုယ်သုံးခဲ့တဲ့ ရင်းမြစ် အားလုံးရဲ့ စာရင်း၊ တစ်ခါတလေ bibliography လို့လည်း ခေါ်ပါတယ်) ထဲမှာ entry တစ်ခု ထည့်ပါ။ Reference (ကိုးကားချက်) တစ်ခုမှာ ရေးသားသူ၊ ထုတ်ဝေတဲ့ ရက်စွဲ၊ ခေါင်းစဉ်နဲ့ ဘယ်မှာ ရှာတွေ့နိုင်လဲ ပါပါတယ် (web page တစ်ခုအတွက်ဆိုရင် သူ့ web လိပ်စာနဲ့ ကိုယ် ကြည့်ခဲ့တဲ့ ရက်စွဲ)။ ရင်းမြစ်မှာ ရက်စွဲ မပါရင် ကိုယ့် referencing style မှာ အဲဒါကို ပြတဲ့ နည်း ရှိပါတယ်၊ ဥပမာ APA (အသုံးများတဲ့ referencing style တစ်မျိုး) မှာ “n.d.” (no date၊ ရက်စွဲ မရှိ) လို့ ရေးပါတယ်။ APA ဒါမှမဟုတ် MLA လို referencing style (ကိုးကားချက်တွေကို ရေးတဲ့ ပုံသေ format) တစ်ခုတည်းကို သုံးပြီး အကြိမ်တိုင်း တစ်ပုံစံတည်း သုံးပါ။

ရင်းမြစ်ကို ဖော်ပြထားရင် ဘယ်အပိုင်းတွေက ကိုယ့်ဟာလဲ၊ ဘယ်အပိုင်းတွေက မဟုတ်လဲ ဆိုတာ ရှင်းရှင်းလင်းလင်း ပြပါတယ်၊ ဒါကြောင့် စာဖတ်သူက ကိုယ့် ကိုယ်ပိုင် အလုပ်အတွက် ကိုယ့်ကို credit ပေးနိုင်ပါတယ်။

IB CS သင်တန်း တက်နေသူတွေအတွက် မှတ်ချက်: IB coursework အားလုံးလိုပဲ Internal Assessment မှာလည်း ကိုယ်သုံးတဲ့ ရင်းမြစ် အားလုံးကို စံ referencing style တစ်ခုနဲ့ တစ်ပုံစံတည်း acknowledge လုပ်ဖို့ လိုပါတယ်။ IB က သတ်မှတ်ထားတဲ့ style တစ်ခုကို မတောင်းပါဘူး၊ ဒါကြောင့် ကိုယ့်ကျောင်း သုံးတဲ့ style ကို သုံးပါ။ ဖော်ပြထားတဲ့ code က plagiarism မဟုတ်ပေမယ့် ကိုယ်ပိုင် programming လည်း မဟုတ်ပါဘူး: IA guide (IA လမ်းညွှန်) က “a programming product using only copied code” (ကူးယူထားတဲ့ code ချည်းပဲ သုံးထားတဲ့ programming product) ကို မသင့်တော်တဲ့ product ဥပမာ တစ်ခုအဖြစ် ပေးထားပါတယ်။ ရင်းမြစ်တွေကို အလုပ်လုပ်ရင်း တစ်ပြိုင်နက် မှတ်ထားပါ၊ အဆုံးမှ လုပ်တဲ့ စာရင်းမှာ တချို့ ကျန်ခဲ့နိုင်ခြေ များပါတယ်။

IB CS သင်တန်း တက်နေသူတွေအတွက် မှတ်ချက်: AI tool များ။ ကိုယ့် IA မှာ သုံးတဲ့ AI output မှန်သမျှအတွက် IB ရဲ့ Academic integrity policy (ပညာရေးဆိုင်ရာ သမာဓိ မူဝါဒ) က ဒါတွေကို တောင်းပါတယ်: ကိုယ့်အလုပ်ရဲ့ ကိုယ်ထည်ထဲမှာ AI output ကို သုံးတဲ့ နေရာမှာ AI tool ကို ကိုယ့်ကျောင်းရဲ့ referencing style နဲ့ credit ပေးရမယ်၊ AI ရေးပေးတဲ့ စာသား မှန်သမျှကို quotation mark ထဲမှာ ထည့်ရမယ်။ Tool ကို ကိုယ့် bibliography ထဲ ထည့်ရမယ်။ ပြီးတော့ ကိုယ်သုံးခဲ့တဲ့ prompt နဲ့ AI က အဖြေ ထုတ်ပေးခဲ့တဲ့ ရက်စွဲကို ပေးရမယ်။ ဒါ့အပြင် ကိုယ့်အလုပ်ကို authenticate (ကိုယ့် ကိုယ်ပိုင် အလုပ် ဟုတ်ကြောင်း အတည်ပြု) လုပ်ပေးမယ့် ဆရာကို AI သုံးခဲ့တာ မှန်သမျှကို ပြောပြပါ၊ reference မလိုတဲ့ သုံးပုံ ဖြစ်နေရင်တောင် ပြောပြပါ။ သုံးခဲ့တာကို ဖော်ပြရုံနဲ့ သုံးပုံ တိုင်းကို လက်ခံနိုင်တယ်လို့ မဆိုလိုပါဘူး: ဥပမာ AI ကို ကိုယ့် IA အလုပ်ကို အမှတ်ပေးခိုင်းတာ ဒါမှမဟုတ် ဘာတွေ ပြင်သင့်လဲ feedback (တုံ့ပြန်ချက်) ပေးခိုင်းတာကို IB က IB assessment (အကဲဖြတ်မှု) တွေအတွက် လက်မခံနိုင်တဲ့ သုံးပုံလို့ သတ်မှတ်ထားပါတယ်။ သဒ္ဒါနဲ့ စာကြောင်း ဖွဲ့စည်းပုံအကြောင်း အကန့်အသတ်နဲ့ အကြံပြုချက်တွေ (တစ်ခုလုံး ပြန်ရေးပေးတာ မဟုတ်) ကိုတော့ ဆရာကို ပြောပြရင် လက်ခံပါတယ်။ အသေးစိတ်နဲ့ IB ရဲ့ ကိုယ်ပိုင် စကားလုံးတွေအတွက် Using AI to write your code (code ရေးဖို့ AI ကို သုံးခြင်း) ကို ကြည့်ပါ။

Quick Check (အမြန် စစ်ဆေးမေးခွန်း)

Q1. User guide ကို ဘယ်သူ့အတွက် ရေးတာလဲ၊ အဲဒါက ဘာလုပ်ပေးလဲ။

Q2. ကောင်းတဲ့ code comment တစ်ခုက များသောအားဖြင့် ဘာကို ရှင်းပြသင့်သလဲ။

Q3. ဘယ် comment က ထားသင့်သလဲ။ (Comment တွေရဲ့ အဓိပ္ပာယ်: A “price ကို total ထဲ ပေါင်းထည့်”၊ B “header row (ခေါင်းစီး row) ကို ကျော်”၊ C “name ကို Sam လို့ သတ်မှတ်”၊ D “x ထဲက တစ် နုတ်”။)

Q4. Online မှာ တွေ့တဲ့ အသုံးဝင်တဲ့ code snippet (code အပိုင်းလေး) တစ်ခုကို ကိုယ့် project ထဲမှာ ပြင်ပြီး ထည့်သုံးပါတယ်။ ရိုးသားတဲ့ လုပ်ရပ်က ဘာလဲ။

Q5. နည်းပညာ မကျွမ်းကျင်တဲ့ user တွေအတွက် user guide တစ်ခုကို ဘာက ထိရောက်စေသလဲ။

Q6. ကောင်းတဲ့ README ထဲမှာ ဘာ ပါသင့်သလဲ။

Document အမျိုးအစား တွဲဖက်ခြင်း

လိုအပ်ချက် တစ်ခုစီအတွက် အသင့်တော်ဆုံး documentation အမျိုးအစားရဲ့ နာမည်ကို ရေးပါ: user guide၊ technical documentation၊ code comment ဒါမှမဟုတ် README။ အဖြေတွေကို English လို ရိုက်ထည့်ပါ။

ကွက်လပ်တွေကို ဖြည့်ပါ။

// A shopkeeper needs to learn how to add a product
// Document: 

// The detailed reference a developer reads before changing the code: design, data and tests
// Document: 

// Explaining, next to a line, why a discount is capped at 50%
// Document: 

// The one-page overview someone sees when they open the project
// Document:

Comment စာကြောင်းတွေရဲ့ အဓိပ္ပာယ် (Document: က “documentation အမျိုးအစား:” လို့ ဆိုလိုပါတယ်):
1. ဆိုင်ရှင် တစ်ယောက်က product (ကုန်ပစ္စည်း) တစ်ခု ထည့်နည်းကို သိဖို့ လိုပါတယ်
2. Developer တစ်ယောက်က code ကို မပြင်ခင် ဖတ်ရတဲ့ အသေးစိတ် ကိုးကားစရာ: ဒီဇိုင်း၊ ဒေတာ နဲ့ test တွေ
3. Discount (လျှော့ဈေး) ကို ဘာကြောင့် 50% မှာ ကန့်သတ်ထားလဲ ဆိုတာကို line တစ်ကြောင်းရဲ့ ဘေးမှာ ရှင်းပြခြင်း
4. Project ကို ဖွင့်လိုက်တဲ့အခါ တွေ့ရတဲ့ တစ်မျက်နှာစာ အကျဉ်းချုပ်

Practice Exercises (လေ့ကျင့်ခန်းများ)

IB CS သင်တန်း တက်နေသူတွေအတွက် မှတ်ချက်: Core 2 နဲ့ Challenge 6 က Internal Assessment ရဲ့ Criterion D တောင်းတဲ့ comment ရေးခြင်းကို လေ့ကျင့်ပေးပြီး Extension 5 က IB coursework အားလုံးမှာ လိုအပ်တဲ့ ရင်းမြစ် ဖော်ပြခြင်းကို လေ့ကျင့်ပေးပါတယ်။

Construct နဲ့ Suggest လို English စကားလုံးတွေက IB command term (မေးခွန်းမှာ ဘာလုပ်ရမလဲ ပြတဲ့ ညွှန်ကြားချက် စကားလုံး) တွေပါ။ (4 marks) လို mark allocation (မေးခွန်း တစ်ခုစီအတွက် ပေးတဲ့ အမှတ်) တွေက IB Computer Science စာမေးပွဲ ပုံစံအတိုင်း ပေးထားတာပါ၊ ဥပမာ (4 marks) ဆိုတာ 4 မှတ်ပါ။ IB သင်တန်း မတက်တဲ့သူတွေကတော့ အဖြေ ဘယ်လောက် အသေးစိတ် ရေးရမလဲ ချိန်ကြည့်ဖို့ လမ်းညွှန်အဖြစ် သုံးနိုင်ပါတယ်။

Core (အခြေခံ အဆင့်)

Construct (ကိုယ်တိုင် တည်ဆောက်ပါ) (4 marks): ကိုယ်သုံးတဲ့ app ဒါမှမဟုတ် program တစ်ခုထဲက task တစ်ခုအတွက် အဲဒါကို တစ်ခါမှ မသုံးဖူးတဲ့သူ တစ်ယောက်အတွက် user guide entry (လမ်းညွှန်ထဲက အပိုင်း တစ်ခု) ကို construct လုပ်ပါ။ ဒီစာမျက်နှာက ဥပမာတွေထဲက တစ်ခု မဟုတ်တဲ့၊ အတန်းထဲမှာ လမ်းညွှန် ရေးပြီးသား မဟုတ်တဲ့ task တစ်ခုကို ရွေးပါ။ Task ရဲ့ နာမည်ကို ဖော်ပြတဲ့ ခေါင်းစဉ် တစ်ခု၊ နံပါတ်တပ်ထားတဲ့ အဆင့် 3 ကနေ 5 အထိနဲ့ တစ်ခုခု မှားသွားရင် ဘာလုပ်ရမလဲ ဆိုတဲ့ မှတ်ချက် တစ်ခု ထည့်ပါ။
Suggest (ဖြစ်နိုင်တဲ့ အဖြေ တစ်ခုကို အကြံပြုပါ) (4 marks): အောက်က comment တစ်ခုစီက သူ့ line ကို ထပ်ပြောရုံပါပဲ။ Line တစ်ခုစီအတွက် အဲဒီ line ဘာကြောင့် ရှိနေလဲ ရှင်းပြတဲ့ comment အသစ် တစ်ခုကို suggest လုပ်ပါ။ ယုတ္တိရှိတဲ့ အကြောင်းပြချက် တစ်ခုကို ကိုယ့်ဘာသာ စိတ်ကူးထည့်လို့ ရပါတယ်။ (a) seats = seats - 2; // subtract 2 from seats (b) points = points * 2; // multiply points by 2 (comment တွေက “seats ထဲက 2 နုတ်” နဲ့ “points ကို 2 နဲ့ မြှောက်” လို့ ဆိုလိုပါတယ်။)
Outline (အကျဉ်းချုပ် ဖော်ပြပါ) (4 marks): အတန်း တစ်တန်းကို အသင်းတွေ ခွဲပေးတဲ့ program တစ်ခုရဲ့ README မှာ line တစ်ကြောင်းပဲ ပါပါတယ်: “Team Picker, by M. Haddad.” (M. Haddad ရေးတဲ့ Team Picker)။ README မှာ ထပ်ထည့်သင့်တဲ့ အချက် လေးချက်နဲ့ အဲဒီ တစ်ချက်စီက project ကို ဖွင့်ကြည့်တဲ့သူကို ဘာကြောင့် အထောက်အကူ ဖြစ်လဲ ဆိုတာကို outline လုပ်ပါ။

Extension (တိုးချဲ့ အဆင့်)

Explain (ရှင်းပြပါ) (4 marks): ကျောင်းရဲ့ quiz night (ညပိုင်း ပဟေဠိ ပြိုင်ပွဲ) မှာ အမှတ်တွေကို မှတ်ထားပေးတဲ့ program တစ်ခုအတွက် ကျောင်းသား တစ်ယောက်က စာရွက်စာတမ်း တစ်ခုတည်း ရေးခဲ့ပါတယ်။ အဲဒီ စာရွက်စာတမ်းထဲမှာ အမှတ်တွေ ထည့်မယ့် ဆရာအတွက် ညွှန်ကြားချက်တွေနဲ့ နောက်နှစ်မှာ program ကို maintain လုပ်မယ့် ကျောင်းသားအတွက် မှတ်စုတွေ ရောနေပါတယ်။ ဘာကြောင့် user guide နဲ့ technical documentation ဆိုပြီး ခွဲသင့်လဲ ဆိုတာ explain လုပ်ပါ။ စာရွက်စာတမ်း တစ်ခုစီမှာ ပါသင့်တဲ့ အချက် တစ်ခုစီကို ဥပမာအဖြစ် သုံးပါ။
Describe (ဖော်ပြရှင်းပြပါ) (6 marks): ကိုယ့် program က ကိုယ်မရေးခဲ့တဲ့ code နှစ်ခုကို သုံးပါတယ်: spreadsheet file တွေကို ဖတ်ပေးတဲ့ အခမဲ့ open-source library တစ်ခု (MIT licence နဲ့ ထုတ်ဝေထားပါတယ်၊ MIT licence က အသုံးများတဲ့ open-source licence တစ်ခုပါ) နဲ့ programming website တစ်ခုပေါ်က tutorial တစ်ခုကနေ ပြင်ပြီး ယူသုံးထားတဲ့ function တစ်ခုပါ။ အဲဒီ နှစ်ခုစီကို ဘယ်လို၊ ဘယ်နေရာမှာ acknowledge လုပ်မလဲ ဆိုတာ describe လုပ်ပါ။

Challenge (စိန်ခေါ်မှု အဆင့်)

Discuss (အမြင် အမျိုးမျိုးကို ချိန်ဆပြီး ဆွေးနွေးပါ) (8 marks): “Comment တွေက code ကို ပိုကောင်းစေတယ်၊ ဒါကြောင့် comment များလေ အမြဲ ကောင်းလေပဲ။” ဆိုတဲ့ ပြောချက်ကို WHY-not-WHAT စည်းမျဉ်း (ဘာ လုပ်လဲ မဟုတ်ဘဲ ဘာကြောင့် လုပ်လဲ ဆိုတာကို comment ရေးခြင်း) နဲ့ ရှုပ်ပွမှုရဲ့ ဆိုးကျိုးကို ကိုးကားပြီး Discuss လုပ်ပါ၊ ပြီးရင် အကြောင်းပြချက် ခိုင်လုံတဲ့ နိဂုံး တစ်ခုကို ချပါ။ (စာပိုဒ်တွေထဲမှာ စာကြောင်း အပြည့်အစုံနဲ့ ရေးပါ။)

ဆက်စပ် ခေါင်းစဉ်များ

ဒီအပိုင်းမှာ အရင် လေ့လာခဲ့တဲ့ ခေါင်းစဉ်: Design Representations: technical documentation ထဲမှာ မကြာခဏ ပါတဲ့ diagram တွေနဲ့ data dictionary
ဒီအပိုင်းမှာ အရင် လေ့လာခဲ့တဲ့ ခေါင်းစဉ်: Testing Strategy: ဘယ်လို run ရမလဲ ဆိုတာကို technical documentation က maintain လုပ်သူကို ပြောပြတဲ့ test တွေ
နောက်ထပ် လေ့လာမယ့် ခေါင်းစဉ်: UI/UX and Accessibility (user interface၊ user experience နဲ့ လူတိုင်း သုံးနိုင်မှု): ကောင်းတဲ့ ဒီဇိုင်းက user guide ရှင်းပြရမယ့် ပမာဏကို လျှော့ပေးပါတယ်
ဆက်စပ် ခေါင်းစဉ်: Ethics of Machine Learning (machine learning ရဲ့ ကျင့်ဝတ်ဆိုင်ရာ ကိစ္စများ): Challenge 6 လို Discuss မေးခွန်း တစ်ခုအတွက် အဖြေကို ဘယ်လို ဖွဲ့စည်း ရေးမလဲ
ဆက်စပ် ခေါင်းစဉ်: Internal Assessment: Criterion D: Development (ကိုယ် တင်ပြတဲ့ code ထဲက comment တွေ၊ တစ်ပုံစံတည်း ဖြစ်မှုနဲ့ ဖတ်ရလွယ်မှု) နဲ့ IA overview (IA ခြုံငုံ မိတ်ဆက်: ဘာတွေ တင်ရမလဲ၊ ရင်းမြစ်တွေကို ဖော်ပြခြင်း)