General

วัตถุประสงค์

เอกสารฉบับนี้จะกล่าวถึงรายละเอียด guideline การเขียนโปรแกรมสำหรับสำนักนวัตกรรมดิจิทัลและระบบอัจฉริยะ เพื่อให้ทีมงานพัฒนาโปรแกรมสามารถมี Boilerplate ในการเริ่มต้นโปรเจคการพัฒนาใหม่ มี Guideline ในการเขียนโค้ดเพื่อให้การพัฒนางานที่ทำให้โปรเจคเสร็จเร็วขึ้น และโปรแกรมเมอร์ทั้งภายในและระหว่างทีมร่วมงานกันได้ง่ายขึ้น

เอกสาร Dev Guideline ฉบับนี้จะกล่าวถึง หัวข้อทั้งหมดต่อไปนี้

1. Software / Library Version / Framework สำหรับการพัฒนาโปรเจค

2. Naming Convention และ Coding Style

1. Software / Library Version / Framework สำหรับการพัฒนาโปรเจค

โปรเจคภายใต้สำนักนวัตกรรมดิจิทัลที่สร้างภายใต้ Dev Guideline ฉบับนี้นั้นจะพัฒนาโดยอาศัย Library / Framework ดังต่อไปนี้

- .NET Core Version 6 LTS (Initial Release Date 8 November 2022) หรือ Version Minor Patch อื่นๆ (เช่น .NET Core 6.x.x)

- Framework สำหรับพัฒนาโปรเจค: ASP.NET Core Blazor Server* - IDE: ใช้ Visual Studio Code, หรือ Visual Studio 2022 ก็ได้ ตามแต่สะดวก (ไม่ควรใช้ Visual Studio 2019 หรือต่ำกว่า เนื่องจากมีปัญหาในการ Support .NET Core 6 ภายใน Program)

2.Naming Convention และ Coding Style

ในหัวข้อนี้จะกล่าวถึง Guideline ในการตั้งชื่อของสิ่งต่างๆในโปรเจค และ Style ในการเขียนโค้ดต่างๆเพื่อให้โค้ดที่เขียนขึ้นมานั้นสามารถสื่อสารกันภายในทีมงานได้ง่ายขึ้น

2.1 Naming Convention

สิ่งที่ต้องทำการ Naming	Guideline ในการตั้งชื่อ	ตัวอย่างการตั้งชื่อ	ตัวอย่างที่ไม่ถูกต้องตาม Guideline
Namespace	DIIS.ชื่อระบบ โดยให้ชื่อระบบเป็น Pascal Case	DIIS.PSULoan	DIIS.psuLoan, HR.sis
Class (Data Model)	Pascal Case	LoanSystem	LOANsystem, loanSytstem
Class (อื่นๆ) / Razor Page / Blazor Component	Pascal Case	LoanSystem	LOANsystem, loanSytstem
Interface Class	Pascal Case แต่ต้องขึ้นต้นด้วย I พิมพ์ใหญ่	ILoanItem	iLoanItem
Property ของ Class (Custom Field)	1. Pascal Case และนำหน้าโดย _ 2. ต้องเป็นคำนาม	_AverageGPA	averageGPA
Public Property ของ Class (อื่นๆ)	Pascal Case	StudentID, HrCode	STUDENT_ID, HR_CODE
Private Variable ของ Class	Camel Case	averageGPA	_averageGPA
Method ภายใน Class ที่เป็น Public / Protected	Pascal Case	ComputeGPA	computeGPA
Method ภายใน Class ที่เป็น Private	Camel Case	computeGPA	ComputeGPA
Method กลุ่ม Create	Insert ตามด้วยชื่อข้อมูล	InsertScore	NewScore,AddScore
Method กลุ่ม Read	Get ตามด้วยชื่อข้อมูล	GetStudentProfile	ListStudentProfile
Method กลุ่ม Update	Update ตามด้วยชื่อข้อมูล	UpdateProfile	profileUpdate
Method กลุ่ม Delete	Delete ตามด้วยชื่อข้อมูล	DeleteScore	RemoveScore,ScoreDelete
Method arguments	Camel Case	GetStudentProfile(string studentID)	GetStudentProfile(string StudentID)
ตัวแปร Local ที่ใช้เฉพาะภายใน Method ใดๆ	Camel Case * ไม่ตั้งชื่อตัวแปรเป็นอักษรเดียว เว้นแต่เป็นตัวแปรกลุ่มวนลูป หรือ ควบคุม Iterator ที่ใช้ภายในสโคปสั้นๆ
ตัวแปร Static หรือ ค่าคงที่	ให้ตั้งชื่อด้วยตัวพิมพ์ใหญ่ทั้งหมด ระหว่างคำให้คั่นด้วย _	IMG_PATH	imgPath, ImgPath
ชื่อไฟล์เอกสาร Text ที่ไม่เกี่ยวข้องกับ Project แต่ใช้อธิบายโปรเจค (เช่น ReadMe)	ให้ตั้งชื่อเป็นตัวอักษรพิมพ์ใหญ่ทั้งหมดเท่านั้น และไม่ต้องระบุสกุล .txt	README,LICENSE	Readme.txt

* กรณีเป็นตัวย่อ ให้ใช้ตัวพิมพ์ใหญ่ทั้งหมดได้ เช่น DIIS, ID, GPA,

2.2 Coding Style

ในหัวข้อนี้จะกล่าวถึง Style ในการเขียนโค้ด เช่น ควรเว้นวรรคแบบใด , การเขียน Comment , บรรทัดใหม่ เป็นต้น Coding Style ที่แนะนำให้ทีมใช้ในฉบับนี้นั้นมีการอ้างอิงมาจากสไตล์ทีแนะนำโดย Microsoft รายละเอียดของสไตล์ที่แนะนำใน Guideline ฉบับนี้ แยกตามหมวดงานนั้น มีดังต่อไปนี้

2.2.1 หมวด Layout ของโค้ด

ในหมวดนี้จะกล่าวถึงการจัดหน้า การเว้นบรรทัดต่างๆเพื่อให้การจัดวาง Layout ของโค้ดในแต่ละบรรทัดอยู่ในทิศทางเดียวกัน Guideline ของหมวด Layout นั้นมีดังต่อไปนี้

• การ Indent และ Tab ให้ใช้ Default Code Editor Setting ของ Visual Studio เท่านั้น ซึ่งได้แก่ (1) ใช้การเว้นวรรค 4 ครั้งแทน 1 Indent และ (2) การกด Tab 1 ครั้งจะได้ผลเป็นการเว้นวรรค 4 ครั้ง

• 1 บรรทัดของการเขียนโค้ดควรมี 1 คำสั่งเท่านั้น

• การประกาศใดๆ (เช่น ตัวแปรต่างๆ, Class, Using, ) ให้ 1 บรรทัดมีได้ไม่เกิด 1 ประกาศ

• ภายใน Class ให้มีการจัดส่วนแบ่งระหว่าง Method, Property และ Class Variable ให้ชัดเจน โดยให้ภายใน Class นั้นมีส่วนของ (1) Property, (2) Class Variable, (3) Method ตามลำดับ

• ระหว่าง Property, Class Variable และ Method ให้มีอย่างน้อย บรรทัดว่าง 1 บรรทัดเพื่อให้อ่านแยกได้สะดวกว่าส่วนใดคือ Property, Class Variable หรือ Method

• การเขียนเงื่อนไข Boolean Expression ให้ใช้วงเล็บจัดสัดส่วนให้โค้ดอ่านง่ายขึ้นเสมอ เช่น

ตัวอย่างที่ควรเขียน

if ( (a < b) && (b > c) ....

ตัวอย่างที่ไม่ควรเขียน

if ( a < b && b > c) .....

2.2.2 หมวดการเขียนและการจัดการ Comment ของโค้ด

• Comment ของโค้ด ไม่ควรอยู่ในบรรทัดเดียวกับโค้ด ควรต้องขึ้นบรรทัดใหม่เท่านั้น

ตัวอย่างที่ควรเขียน

// Intializing variable
Int studentTest = 50;

ตัวอย่างที่ไม่ควรเขียน

Int studentTest = 50; // Initializing variable

• หลังเครื่องหมาย Comment ให้เว้นวรรค 1 ช่องว่างเสมอก่อนใช่ข้อความ Comment

ตัวอย่างที่ไม่ควรเขียน:

//This is my comment

ตัวอย่างที่ควรเขียน:

// This Is my comment

• หลีกเลี่ยงการใช้เครื่องหมาย /* */ ในการเขียน Comment เพื่อป้องกันปัญหาการสับสนของ Nested Comment และการสับสนสัญลักษณ์ * ของส่วน comment และ ส่วนโค้ดจริงๆ กล่าวคือควรใช้ // ในการ comment เป็นหลักเท่านั้น

• ภาษาที่ใช้ในการ Comment ใช้ภาษาไทยหรืออังกฤษก็ได้ตามแต่ตกลงภายในทีมงานของแต่ละโปรเจค

• ควรใช้ /// เพื่อ comment กำกับทุกๆ Method ที่เป็น public เพื่อความสะดวกในการใช้ Tool ในการ Generate Document ที่มีการ support XML Documentation Style

ตัวอย่าง

///<summary>
/// This class performs an important function.
/// </summary>
public class MyClass 
{

    /// <summary>
    /// Sample mockup method
    /// </summary>
    /// <returns>Mockup return value</returns>
    public string SampleMethod ()
    {
        return "test";
    }

}

รายละเอียดว่า syntax ของ XML Documentation Style มีอะไรบ้างอ่านเพิ่มได้ที่ https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/