Code Style規範

2021-12-27

252
0
軟體協作
2022-05-27

規範

0.變數

0.0.0 命名

變數名稱應該要簡單，並能代表它的意思，表達出來。

建議

var product = new Product();

不建議

var p = new Product();
var produ = new Product();

Lambda規範

建議

products.Where(product => product ... );

不建議

products.Where(p => p ... );

關於複數，用在集合或陣列

0.0.1 複數

建議

var products = new List<Product>();

不建議

var productList = new List<Product>();

0.0.2 類型名稱

建議

var product = new Product();

不建議

var productModel = new Product();

不建議

var productObj = new Product();

1 方法

1.0 命名

方法的命名應該要執行操作的摘要，它需要保持準確和簡短

1.0.0 動詞

方法名稱中必須包含動詞來表示它執行的操作。

建議

public List<Student> GetStudents() 
{ 
	...
}

不建議

public List<Student> Students() 
{ 
   ...
}

1.0.1 異步

非同步方法應該放置動詞的操作方法後面 Async 通常返回的方法應該返回 Task 或 ValueTask 。

建議

public async ValueTask<List<Student> GetStudentsAsync() 
{ 
	...
}

不建議

public async ValueTask<List<Student> GetStudents() 
{ 
	...
}

1.0.2 方法參數

方法參數應該明確說明它們給予的物件或是它的意思

建議

public async ValueTask<Student> GetStudentByNameAsync(string studentName) 
{ 
	... 
}

不建議

public async ValueTask<Student> GetStudentByNameAsync(string text) 
{ 
	...
}

不建議

public async ValueTask<Student> GetStudentByNameAsync(string name) 
{ 
	...
}

1.0.3 動作參數

如果您的方法正在使用特定參數執行操作，請指定它。

建議

public async ValueTask<Student> GetStudentByIdAsync(Guid studentId) 
{ 
	... 
}

不建議

public async ValueTask<Student> GetStudentAsync(Guid studentId) 
{
	 ... 
}

1.0.4 傳遞參數

在使用方法時，如果輸入參數別名與傳入的變量部分或全部匹配，則不必使用別名，否則必須使用別名指定值。

假設你有一個方法：

Student GetStudentByNameAsync(string studentName);

建議

string studentName = "Todd"; Student student = await GetStudentByNameAsync(studentName);

建議

Student student = await GetStudentByNameAsync(studentName: "Todd");

建議

Student student = await GetStudentByNameAsync(toddName);

不建議

Student student = await GetStudentByNameAsync("Todd");

不建議

Student student = await GetStudentByNameAsync(todd);

1.1 組織

一般來說，將多行相同的邏輯封裝到自己的方法中，並始終將您的方法保持在細節級別 0。

1.1.0 一行的狀況

任何只包含一行代碼的方法都應該使用粗箭頭。

建議

public List<Student> GetStudents() => this.storageBroker.GetStudents();

不建議

public List<Student> Students()
{
	return this.storageBroker.GetStudents();
}

如果單行方法超過 120 個字符的長度，則在粗箭頭後用一個額外的製表符換行。

1.1.1 回傳

對於多行方法，在方法邏輯和最終返回行（如果有）之間換行。

建議

public List<Student> GetStudents(){
	StudentsClient studentsApiClient = InitializeStudentApiClient();

	return studetnsApiClient.GetStudents();
}

不建議

public List<Student> GetStudents(){
	StudentsClient studentsApiClient = InitializeStudentApiClient();
	return studetnsApiClient.GetStudents();
}

1.1.2 關於呼叫

對於多個方法調用，如果兩個調用都少於 120 個字符，則它們可能會堆疊，除非最終調用是方法返回，否則用新行分隔

建議

public List<Student> GetStudents()
{ 
   StudentsClient studentsApiClient = InitializeStudentApiClient();
   List<Student> students = studetnsApiClient.GetStudents();
   
   return students;
}

不建議

public List<Student> GetStudents()
{
   StudentsClient studentsApiClient = InitializeStudentApiClient(); 
   
   List<Student> students = studetnsApiClient.GetStudents();
   
   return students;
}

建議

public List<Student> GetStudents()
{ 
    StudentsClient washingtonSchoolsStudentsApiClient = 
             await InitializeWashingtonSchoolsStudentsApiClientAsync();   		
    
    List<Student> students = studetnsApiClient.GetStudents(); 
    return students;     
}

不建議

public List<Student> GetStudents()
{   
     StudentsClient washingtonSchoolsStudentsApiClient =
                    await InitializeWashingtonSchoolsStudentsApiClientAsync(); 
     List<Student> students = studetnsApiClient.GetStudents(); 

     return students;
}

1.1.3 宣告

建議

public async ValueTask<List<Student>> GetAllRegisteredWashgintonSchoolsStudentsAsync(
       StudentsQuery studentsQuery)
{
   ... 
}

不建議

public async ValueTask<List<Student>> GetAllRegisteredWashgintonSchoolsStudentsAsync(StudentsQuery studentsQuery)
{
	...
}

1.1.4 多參數

如果要傳遞多個參數，並且方法調用的長度超過 120 個字符，則必須以參數分隔，每行一個參數。

建議

List<Student> redmondHighStudents = await QueryAllWashingtonStudentsByScoreAndSchoolAsync(
	MinimumScore: 130,
	SchoolName: "Redmond High");

不建議

List<Student> redmondHighStudents = await QueryAllWashingtonStudentsByScoreAndSchoolAsync(
	MinimumScore: 130,SchoolName: "Redmond High");

4 類別

4.0 命名

在 MBSCV 體系結構中表示服務或代理的類應在其命名約定中表示類的類型，但這不適用於模型。

4.0.0 模型

建議

class Student
{
   ... 
}

不建議

class StudentModel 
{

}

4.0.1 服務

以一種獨特的方式，對於任何包含業務邏輯的類。

建議

class StudentService { .... }

不建議

class StudentsService{ ... }

不建議

class StudentBusinessLogic 
{
   ...
}

不建議

class StudentBL 
{ 
  ... 
}

4.0.3 控制器

以復數方式，反映 /api/students 等端點，以通過 RESTful 操作公開您的邏輯。

建議

class StudentsController {
   .... 
}

不建議

class StudentController {
    ... 
}

4.1 屬性

字段是直接在類或結構中聲明的任何類型的變量。字段是其包含類型的成員。

4.1.0 命名

類字段以駝峰式命名。

建議

class StudentsController {
	private readonly string studentName;
}

不建議

 class StudentController {
	private readonly string StudentName;
}

不建議

class StudentController {
	private readonly string _studentName;
}

應遵循與變量部分中提到的相同的命名規則。

4.1.1 參考

建議

class StudentController {
	private readonly string _studentName;

	public StudentsController(string studentName) {
		_studentName = studentName;
	}
}

不建議

class StudentsController {
	private readonly string _studentName;
	
	public StudentsController(string studentName) {
		this.studentName = studentName;
	}
}

4.2 實例化

4.2.0 輸入參數別名

如果輸入變量名稱與輸入別名匹配，則使用它們，否則必須使用別名，尤其是傳入的值。

建議

int score = 150;
string name = "Josh";

var student = new Student(name, score);

建議

var student = new Student(name: "Josh", score: 150);

不建議

var student = new Student("Josh", 150);

額外補充：https://www.dofactory.com/csharp-coding-standards#abbreviations

元哥的筆記

軟體協作

回首頁