Coding Standards Part-II

ေဆာ့ဖ္ဝဲနဲ့ ပတ္သက္တဲ့ မွတ္တမ္းမွတ္ရာ(Software Documentation) ဟာ ပံုစံနွစ္မို်းနဲ့ ရိွနိုင္ပါတယ္။

တစ္မို်းကေတာ့ Source Code ရဲ့ ျပင္ပမွာ သီးျခားေရးသားျပုစုထားတဲ့ External Documentations ေတြျဖစ္ၾကတဲ့ Business Requirement Specification, System Requirement Specification, Detailed Design Specification, User Manual Documentation[Help File] စတာေတြျဖစ္ပါတယ္။

ေနာက္တစ္မို်းကေတာ့ ပရိုဂရမ္ေရးသားေနစဉ္ကာလမွာပဲ Source Code ရဲ့ အတြင္းမွာ တျပိုင္တည္းေရးသား သြားတဲ့ Internal Documentation တနည္းေျပာရရင္ေတာ့ Comment ေတြပဲေပါ့ဗ်ာ။

ဒီ Comment ေတြဟာ Run Time မွာ ဘာမွလုပ္မေပးနိုင္ေပမဲ့၊ Maintenance လုပ္တဲ့အခိ်န္မွာေတာ့ သိပ္ကို ၾကီးမားထိေရာက္တဲ့ အကူအညီေတြ ေပးနိုင္ပါတယ္။ ဒါေၾကာင့္ ေကာင္းမြန္ရွင္းလင္းတဲ့ Comment ေတြ ရဖို့ အတြက္ ေအာက္ပါအခ်က္ေတြနဲ့ အညီ ေဆာင္ရြက္သင့္ပါတယ္။

Java နဲ့ေရးရင္ java doc (java documentation) tool နဲ့ ကိုက္ညီမယ့္ပံုစံ၊ C# နဲ့ေရးရင္ XML Documentation Feature နဲ့ ကိုက္ညီမယ့္ ပံုစံနဲ့ ေရးပါ။

[ ဒီအေၾကာင္း အေသးစိပ္ သိလိုတယ္ဆိုရင္ သက္ဆိုင္ရာ စာအုပ္စာတမ္းမ်ား၊ ကြ်မ္းက်င္သူမ်ားထံမွာ ေလ့လာေမးျမန္းၾကပါ။ ဒီေနရာမွာေတာ့ အခ်က္အလက္ေတြ သိပ္မ်ားျပားရႈပ္ေထြးကုန္မွာစိုးတဲ့အတြက္ ခ်န္လွပ္ခဲ့ပါရေစဦး။]

Source Code ကို ျပင္ဆင္တယ္ဆိုရင္ သူနဲ့သက္ဆိုင္တဲ့ comment ေတြကိုပါ လိုအပ္ရင္ တခါတည္းျပင္ပါ။

Method, Function တိုင္းရဲ့အစမွာ၊ ဒီ Method ရဲ့ ရည္ရြယ္ခ်က္၊ ယူဆခ်က္၊ အကန္ ့အသတ္၊ စတာေတြအျပင္ ဒီ Method ဟာ ဘာလုပ္နိုင္တယ္၊ သူ ့ကို ဘာေၾကာင့္ေရးရတယ္၊ ဘယ္ အညွြန္း BRS, SRS ေၾကာင့္ ေရးတယ္၊ ဒီ Method ကို ေခၚရင္ ဘာ Parameter ေတြထည့္ေပးရမယ္၊ သူက ဘာကို Return ျပန္ေပးမယ္ ဆိုတာေတြကို ပံုစံတက် ျပည့္ျပည့္စံုစံု comment ေရးသားေပးပါ။

Variable ေၾကညာျပီး သူ ့ရဲ့ လိုင္းအဆံုးမွာ indent ျခားျပီး ဒီ variable ကို ဘာအတြက္သံုးတာ… ဆိုတဲ့ ခပ္တိုတို comment မို်းကလဲြျပီး၊ အဲဒီလို ‘လိုင္းအဆံုးတြင္ေရးေသာမွတ္ခ်က္’ (end-line comment) ေတြကို တတ္နိုင္သေလာက္ ေရွာင္က်ဉ္ပါ။

Comment နဲ ့ coding ကို blank line သို ့မဟုတ္ white space နဲ ့ပဲ ခဲြျခားပါ။ Asterisks(*) [ VB မွာေတာ့ Single quote ေပါ့ဗ်ာ..] ေတြကို လိုင္းတလိုင္းစာသံုးျပီး ပိုင္းျခားတာမို်း၊ comment ေတြကို ပတ္ပတ္လည္ေဘာင္ခတ္ထားတဲ့ပံုစံ (typographical frame) မို်း ေရွာင္က်ဉ္ပါ။ ၾကည့္ရတာ မိုက္ သလိုလိုရိွေပမယ့္ ၊ Maintenance လုပ္တဲ့အခါ ၊ တခါတေလ သူ ့အတြက္နဲ ့ အလဟႆ အခိ်န္ကုန္တတ္ပါတယ္။

ျပီးေတာ့ မိတ္ေဆြရဲ့ Application ကို deploy မလုပ္မီ (Installer မျပုလုပ္မီ) Program ေတြအတြင္းမွာ ယာယီသံုးစဲြထားတဲ့ မွတ္ခ်က္ေတြ၊ မလိုအပ္ပဲ ပံုလံွ်ေနတဲ့ comment ပိတ္ထားတဲ့ လိုင္းေတြ၊ to do list စတာေတြ အားလံုးကို ရွင္းလင္းဖယ္ရွား(ဖ်က္) ပစ္ပါ။

တကယ္လို ့ မိတ္ေဆြဟာ၊ ရႈပ္ေထြးတဲ့ Programing Logic တခုနဲ ့ ပတ္သက္ျပီး ရွင္းလင္းျပမယ့္ comment မို်းေရးေတာ့မယ္ဆိုပါစို ့။ ဒီလို comment မို်းေရးမယ့္အစား၊ ရႈပ္ေထြးေနတဲ့ Programming Logic ကိုသာ ပိုမိုရွင္းလင္းသြားေအာင္ ၾကိုးစားျပီး ျပန္ျပင္ေရးၾကည့္ပါဦး။ ‘ရွင္းေအာင္မလုပ္နိုင္ရင္ မိုက္မဲရာက်မွာေပါ့’ ဆိုတဲ့ KISS(Keep It Simple, Stupid!)Principle ကို သတိရပါ။

Comment ေတြကို အဓိပၸါယ္ေပၚလြင္ေအာင္ ၀ါက်ျပည့္စံုစြာတည္ေဆာက္ေရးသားပါ။ ရွင္းျပလိုက္မွ ပိုရႈပ္သြားတာမို်း၊ အဂၤလိပ္ေတြနားမလည္တဲ့ အဂၤလိပ္စကားမို်းေတာ့ မျဖစ္ေစနဲ ့ေပါ့ဗ်ာ။

Loop ေတြ (for, foreach, while, do…while) နဲ ့ logical branch (if, if else, switch, ternary operator [or] conditional operator ? :) ေတြမွာ၊ comment ေရးပါ။

ဒါေတြဟာ Source Code ရဲ့ တကယ့္အေရးပါတဲ့ေနရာေတြေပါ့။ မိတ္ေဆြကိုယ္တိုင္ေတာင္ ကိုယ္ေရးထားတဲ့ Application တခုကို ေနာက္ တစ္လ တစ္လခဲြ ေလာက္ၾကာတဲ့အခိ်န္ ျပန္ဖတ္တဲ့အခါ၊ အဲဒီလိုမို်း comment ေတြဟာ အလြန္ အကို်းရိွတာ ေတြ ့ရမွာပါ။

ကဲ အခု ကြ်န္ေတာ္တို ့ source code ရဲ့ ပံုပန္းသဏန္ သြင္ျပင္လကၡဏာ (format)ေတြ အေၾကာင္း ဆက္ျပီးေတာ့ ေလ့လာလိုက္ၾကပါဦးစို ့။

3. Format

C C++, Java, C# စတဲ့ language ေတြမွာ မျဖစ္မေနသံုးရတဲ့ တြန္ ့ကြင္း(curly braces) နဲ ့ပတ္သက္ျပီး အရင္ဆံုးတင္ျပခ်င္ပါတယ္။ Java မွာေတာ့ class, interface, method, constructor, block(try-catch, static, if, switch, for, while, do, etc) စတဲ့ declaration ေတြျပီးတာနဲ ့ ခ်က္ခ်င္း space တစ္ခုျခားျပီး တြန္ ့ကြင္း စ ဖြင့္ရပါမယ္။ ဒါဟာ Java မွာ must be ပါ။ တြန္ ့ကြင္းပိတ္တဲ့ အခါ အဲဒီ declaration ရဲ့ အစ စာလံုးေအာက္တည့္တည့္ ေဒါင္လိုက္ တတန္းတည္းျဖစ္ရပါမယ္။ ဥပမာ

anyBlock() {

}

C# မွာေတာ့ .NET IDE က အဖြင့္ ကြင္း နဲ ့ အပိတ္ကြင္းကို တတန္းတည္း ထားတဲ့ပံုစံကို သံုးပါတယ္။ ဥပမာ

AnyBlcok()

{

}

ဒါေၾကာင့္ ကြ်န္ေတာ္တို ့ အထက္မွာ ေဆြးေနြးခဲ့သလို တခို် ့အရာေတြကေတာ့ ‘တေက်ာင္း တဂါထာ’ ျဖစ္တဲ့အတြက္၊ သူ ့ေက်ာင္းေနရင္ သူ ့စာ အံ လိုက္ေပါ့ဗ်ာ။ သတိထားဖို ့တခုကေတာ့ IDE ေတြ Editor ေတြက generate လုပ္ေပးတဲ့ code က format တမို်း၊ ကိုယ္ကိုတိုင္ ေရးတဲ့ ကုဒ္ ေတြက format တမို်းေတာ့ မျဖစ္ေစနဲ ့ေပါ့ဗ်ာ။ Program တစ္ေလ်ာက္လံုးမွာ format တမို်းတည္းကိုပဲ ပံုေသသံုးစဲြ သင့္ပါတယ္။

Indent ေတြကို မျဖစ္မေနသံုးစဲြပါ။ Java မွာ one indent level ဟာ 4-spaces ရိွရပါမယ္။ C# အတြက္လည္း အလားတူ ယူဆနိုင္ပါတယ္။

မိတ္ေဆြ source code ရဲ့ လိုင္းတလိုင္းမွာ ပါမယ့္ character အေရအတြက္ကို အတိအက် သတ္မွတ္ထားပါ။ [ဥပမာ 65-characters per line စသည္ျဖင့္ေပါ့။] ဒါမွသာ source code ကို soft copy အေနနဲ ့ ဖတ္တဲ့အခါ၊ Horizontal Scrollbar သံုးစရာ မလိုတဲ့အျပင္၊ Hard Copy အျဖစ္ ဖတ္ရႈတဲ့အခါမွာလည္း ပံုမပ်က္ မရႈပ္ေထြးေတာ့ဘူးေပါ့။

Uninary Operator(++, --, +=, -=, etc..) ေတြကလဲြရင္ Binary Operator, assignment operator ေတြရဲ့ ေရွ ့နဲ ့ ေနာက္ မွာ space တခုစီ သံုးေပးပါ။ ဥပမာ

int a=4; bad

int a = 4; good

c=a+b; bad

c = a + b; good

စသည္ျဖင့္ေပါ့ဗ်ာ။ ဒီေလာက္ဆို မိတ္ေဆြတို ့ ေကာင္းေကာင္းသိပါတယ္။ concatenation operator ( + ) ကို သံုးစဲြရင္ ပထမလိုင္းရဲ့ ေနာက္ဆံုးမွာပဲထားပါ။ ဒုတိယ လိုင္းရဲ့ ေရွ ့ဆံုးမွာ မထားပါနဲ ့။ ဥပမာ

String longDesc = “This is a very long description, …..to be continue” +

“this is the continuation of the previous line”;

For loop ကလဲြလို ့ လိုင္းတလိုင္းမွာ statement တခုထက္ ပိုမေရးသင့္ပါဘူး။

Html ေရးတဲ့အခါ tags ေတြအားလံုးကို အၾကီး(upper case)၊ attributes ေတြကို အေသး(lower case)၊ attribute ရဲ့ value ေတြကို သင့္ေလ်ာ္ရာ single quote သို ့မဟုတ္ double quote ေတြ သံုးျပီးေရးသားပါ။ XML ေရးရာမွာလည္း opening tag တိုင္းအတြက္ သက္ဆိုင္ရာ closing tag ေတြကို သံုးစဲြပါ။

SQL statement ေတြအတြက္ keyword အားလံုး အၾကီး၊ database element/object (table, column, view) ေတြအတြက္ အၾကီးအေသးေရာ(mixed case) ပံုစံနဲ ့ေရးပါ။ ဒါ့အျပင္ major clause တိုင္းကို တစ္လိုင္းစီ ေရးပါ။ ဥပမာ

SELECT FieldOne, FieldTwo, …..

FROM TableOne, TableTwo

WHERE (bla bla relationship of two tables)

AND FieldSomething LIKE ‘ something’

OR FieldNo = 999;

ကြ်န္ေတာ္တို ့ အခုေဆြးေနြးခဲ့တာေတြက ျပည့္စံုမႈမရိွေသးေပမယ့္လည္း ေယဘုယ် အေျခခံအခ်က္အလက္ ေတြကိုေတာ့ သိခဲ့ရျပီေပါ့ဗ်ာ။ ဒီအခ်က္အလက္ေတြအတိုင္း လိုက္နာေဆာင္ရြက္နိုင္မယ္ ဆိုရင္ေတာင္ မိတ္ ေဆြရဲ့ source code ေတြဟာ ရွင္းလင္းသပ္ရပ္မႈ (Simplicity and Clearity) ရိွလာမယ္။ ဒီရဲ့ အကို်းဆက္ အျဖစ္ ဖတ္ရႈနားလည္နိုင္စြမ္း (Readability and Understandability) တက္လာမယ္။ ဒါေၾကာင့္ ျပင္ဆင္နိုင္စြမ္း (Maintainability) ျမင့္မားလာျပီး ျပင္ဆင္ထိန္းသိမ္းမႈ ကုန္က်စရိတ္ (Maintenance Cost) ေလ်ာ့က်လာနိုင္ပါတယ္။ ဒီအခ်က္အလက္ေတြဟာ C, C++ , Java ပရိုဂရမ္မာေတြ ၊ အဲဒီ language ေတြ ေက်ာေထာက္ေနာက္ခံရိွတဲ့ C# ပရိုဂရမ္မာေတြ အတြက္ အနည္းနဲ့ အမ်ား ရင္းနီွးျပီးသားျဖစ္မွာပါ။ အေရးအၾကီးဆံုးအခ်က္ကေတာ့ ပရိုဂရမ္ စေရးေရးျခင္း

    “Start ကို နိွပ္ပါ။ ဘာကိုဖြင့္ပါ။ File menu ထဲက New Project ကိုေရြးပါ။ ဘာလုပ္ပါ။ ညာလုပ္ပါ။ F5 ကိုနိွပ္၍ Run ပါ”

ဆိုတဲ့ သင္ၾကားခ်က္မို်း လုပ္ေဆာင္ခ်က္မို်း က ရလာတဲ့ ပရိုဂရမ္ေတြ အေပၚမွာ ေသာင္တင္ယစ္မူး ေနတဲ့ အျဖစ္မို်း မေရာက္ေအာင္ ပရိုဂရမ္ကို စတင္ေလ့လာသင္ယူေနတဲ့ မိတ္ေဆြတို ့ အထူးသတိထား သင့္တယ္ဆိုတာပါပဲ။ ဒီလိုေျပာတာဟာ IDE(Integrated Development Environment) ကို ပစ္ပယ္တာမဟုတ္ပါဘူး။ တကယ္ေတာ့ IDE ဟာ ၀ါရင့္ သမၻာရင့္ ပရိုဂရမ္မာေတြအတြက္ေတာင္ မရိွမျဖစ္ နီးနီး သိပ္ကို အေရးၾကီးတဲ့ ၊ ေဆာဖ့္ဝဲေရးသားထုတ္လုပ္နိုင္စြမ္း (Software Productivity) ကို အမ်ားၾကီး ျမွင့္တင္ေပးနိုင္တဲ့ tool တစ္ခုပါ။

ဒါေပမယ့္ လူသစ္တန္း ပရိုဂရမ္စတင္ေလ့လာသူေတြဟာ (ျဖစ္နိုင္သေလာက္) ရိုးရိုး text editor နဲ ့ command line tools ေတြကိုပဲ သံုးစဲြျပီး၊ ကိုယ္ေရးတဲ့ပရိုဂရမ္ကို ‘အပ္ က်တာကအစ သိေနေအာင္’ အရင္ဆံုး အားထုတ္သင့္ပါတယ္။ အဲဒီလိုမွ မဟုတ္ရင္ေတာ့ ဒါဟာ “ပန္းတိမ္ မတတ္ခင္ ေရွြ ခိုးသင္” ဆိုတာထက္ကို ဆိုးဝါးတဲ့ ၊ “ပန္းတိမ္ မသင္ ခင္ ၊ ေရွြ ခိုးသင္” သလို ျဖစ္ေနနိုင္ပါေၾကာင္း…။