Coding Standard 4.0

Trường Đại Hoc Khoa Hoc Tự Nhiên Khoa Công Nghệ Thông Tin Môn Hoc : Xây Dựng Phần Mềm  Giáo Viên : Ngô Huy Biên Version 4.0 Date: 17/05/2011 Writer by Group I – XDPM XDPM_Nhóm I(Phụ trách nhóm 8) Page STT I Thời Gian 21/03/2011 22/04/2011 13/05/2011 17/05/2011 Version 1.0 2.0 3.0 4.0 Nội Dung Hoàn thiện dần nội dung chuẩn mã nguồn Hoàn thiện dần nội dung chuẩn mã nguồn Hoàn thiện dần nội dung chuẩn mã nguồn Hoàn thành tài liệu chuẩn mã nguồn Người Thực Hiện Nhóm I Nhóm I Nhóm I Nhóm I Giới Thiệu : Mục Đích: Theo yêu cầu Thầy tạo hiệu cao việc phát triển phần mềm , thống phong cách giảm chi phí cho việc sửa lổi , bảo trì hệ thống Nhóm I xây dựng tài liệu đưa số đề xuất mô tả luật thống cho việc xây dựng phần mềm quản lý Ký Túc Xá mà nhóm xây dựng mơn hoc Xây Dựng Phần Mềm Phạm vi tài liệu: Tài liệu áp dụng chuẩn C# dụng công nghệ WPF cụ thể chuẩn cứu pháp chuẩn ngữ nghĩa Sẽ qui định cụ thể phần Tài liệu nhóm sinh viên thực nên có nhiều thiếu sót mong góp ý Thầy Cơ bạn Tài liệu tham khảo : - II Tham khảo slide thuyết trình nhóm chuẩn mã nguồn thực môn hoc Bộ chuẩn mã nguồn phần mềm hoc toán lớp 11 Bộ chuẩn mã nguồn phần mềm hoc toán lớp Bài viết chuẩn mã nguồn Wikipedia Có tham khảo phần mềm StyleCop Qui Ước Đặt Tên Qui ước viết hoa : 1.1 Pascal case – cú pháp Pascal Ví dụ: BackColor XDPM_Nhóm I(Phụ trách nhóm 8) Page Camel case – cú pháp Lạc đà Ký tự từ viết thường ký tự từ viết hoa Ví du: 1.2 backColor Uppercase Tất ký tự viết hoa Chỉ sử dụng quy ước cho tên bao gồm vài ký tự Ví dụ: 1.3 System.IO; System.Web.UI; Tùy vào trường hợp mà sử dụng quy ước trên, chẳng hạn viết hoa tất thường sử dụng cho giá trị constant Sau bảng quy tắc với ví dụ: Identifier Case Example Class Pascal AppDomain Enum Type Pascal ErrorLevel Enum Value Pascal FatalError Event Pascal ValueChange Exception class Pascal WebException Note: Always ends with the suffix Exception Read-only Static field Pascal RedValue Interface Pascal IDisposable Note: Always begins with the prefix I Method Pascal ToString Namespace Pascal System.Drawing Parameter Camel typeName Property Pascal BackColor Protected instance field Camel redValue Note: Rarely used A property is preferable to XDPM_Nhóm I(Phụ trách nhóm 8) Page Identifier Case Example using a protected instance field Public instance Pascal field RedValue Note: Rarely used A property is preferable to using a public instance field Qui Ước Viết Tắt Để tránh nhầm lẫn lạm dụng viết tắt, sau quy tắc việc viết tắt: Không sử dụng quy ước viết tắt viết rút gọn định danh tên Ví dụ, sử dụng GetWindow thay GetWin • Không sử dụng acronym - từ mà cấu tạo từ chữ đầu nhóm từ mà khơng chấp nhận lĩnh vực máy tính • Trong trường hợp thích hợp, tốt sử dụng acronym để thay cho tên dài Ví dụ, sử dụng UI thay cho User Interface and OLAP thay cho On-line Analytical Processing • Khi sử dụng acronym, sử dụng cú pháp Pascal Lạc đà cho acronym có nhiều ký tự Ví dụ, sử dụng HtmlButton htmlButton Tuy nhiên, nên viết hoa tât ký tự gồm ký tự, chẳng hạn System.IO thay System.Io • Khơng viết tắt định danh tham biến Nếu phải viết tắt sử dụng cú pháp Lạc đà từ có nhiều ký tự mâu thuẫn quy ước viết tắt • Chi tiết chuẩn 3.1 Qui tắc đặt tên namespaces Quy tắc chung cho việc đặt tên namespaces sử dụng tên công ty theo sau tên cơng nghệ có chức thiết kế theo sau CompanyName.Technology[.Feature][.Design] Ví dụ: Microsoft.Media Microsoft.Media.Design - Tên namespace bắt đầu với tên công ty nhãn khác tránh tình trạng hai namespace tên Ví dụ, Microsoft.Office XDPM_Nhóm I(Phụ trách nhóm 8) Page - - - - Namespace phải bao gồm kiểu mà yêu cầu lúc thiết kế hàm cho namespace sở với hậu tố Design Ví dụ, namespace System.Windows.Forms.Design bao gồm trình thiết kế có liên hệ với lớp sở System.Windows.Forms Có lệ thuộc kiểu namespace Chằng hạn, lớp the System.Web.UI.Design lệ thuộc vào lớp System.Web.UI Tuy nhiên lớp System.Web.U không lệ thuộc vào lớp System.Web.UI.Design Sử dụng cú pháp Pascal, ngăn cách thành phần logic với dấu chấm ( ), Microsoft.Office.PowerPoint Sử dụng tên namespace số nhiều thích hợp Chằng hạn, sử dụng System.Collecions System.Collection Không kể trường hợp tên viết tắt Chằng hạn sử dụng System.IO System.IOs Không sử dụng tên cho namespace class Ví dụ, khơng có namespace Debug lớp Debug  Tránh sử dụng từ khóa Using namespace : namespace CodingStandardChecker; { using system = System; }  Gom tất namespace nhà cấp thành nhóm, namespace tạo theo nhóm: using System; using System.Collections.Generic; using System.Linq; using System.Text; using MyNameSpace; using MyLibrary; Cuối cùng, ý tên namespace khơng có song song với thư viện liên kết có tên 3.2 Qui tắc đặt tên Lớp • Sử dụng danh từ cụm danh từ • Sử dụng cú pháp Pascal • Hạn chế viết tắt XDPM_Nhóm I(Phụ trách nhóm 8) Page Không sử dụng kiểu tiền tố, C cho class, class name ví dụ, sử dụng tên class FileStream CFileStream • • Khơng sử dụng ký tự gạch (_) • Đơi tên class bắt đầu với ký tự I, class khơng phải interface • Thỉnh thoảng, sử dụng từ ghép cho lớp dẫn xuất Thành phần thứ hai tên lớp dẫn xuất tên lớp sở Ví dụ, ApplicationException tên lớp dẫn xuất từ lớp Exception, ApplicationException loại Exception • Sau cách đặt tên lớp quy tắc: public class FileStream public class Button public class String • • Tên Class phải phản ánh nội dung chứa Phần mềm xây dựng theo mơ hình lớp nên tên Class qui định sau : Tên đối tượng + Tên lớp(BUS, DAO, DTO) VD : KhuBUS , KhuDAO , SinhVienDAO ……  Khi sử dụng kiểu partial để chia lớp thành nhiều file phải đặt tên file với tên lớp nhiệm vụ mà phần lớp chứa file đảm nhiệm cách logic: Trong file MyClass.cs: chứa thuộc tính phương thức thực thi lớp public partial MyClass { } Trong file MyClass.Designer.Cs: Chứa phương thức khởi tạo vẽ giao diện lớp public partial MyClass { }  Tên file chứa source code lớp(class) phải tên với lớp 3.3 Qui tắc đặt tên Form Đặt tên theo Pascal case phản ảnh cơng việc mà form thực VD : QuanLyDienNuoc , ThongTin , QuanLyPhong XDPM_Nhóm I(Phụ trách nhóm 8) Page 3.4 Qui tắc đặt tên kiểu liệu Đặt tên theo Pascal case phản ảnh nội dung liệu mà file lưu trữ , Nếu tên từ viết tắt sử dụng theo Upper case VD : RangBuoc.xml , KTX.mdf 3.5 Qui tắc đặt tên kiểu Enum Giá trị kiểu Enum kế thừa từ lớp Enum Sau quy tắc đặt tên cho enumerations: • Sử dụng cú pháp Pascal cho kiểu Enum giá trị tên • Hạn chế viết tắt • Khơng sử dụng hậu tố Enum tên kiểu Enum • Sử dụng tên số cho hầu hết kiểu Enum Ví dụ, khơng đặt tên Protocols mà đặt Protocol public enum Protocol { Tcp, Udp, Http, Ftp } • Sử dụng tên số nhiều cho kiểu Enum mà có trường bit Ví dụ: [Flags] public enum Protocol { CaseInsensitive = 0x01, WholeWordOnly = 0x02, AllDocuments = 0x04, Backwards = 0x08, AllowWidlcards = 0x10 } • Thường xuyên thêm FlagsAttribute đến trường bit kiểu Enum 3.6 Qui tắc đạt tên cho trường Static • Sử dụng danh từ, cụm danh từ danh từ viết tắt • Sử dụng cú pháp Pascal XDPM_Nhóm I(Phụ trách nhóm 8) Page • Không sử dụng cú pháp Hungarian cho tên trường static • Nên sử dụng thuộc tính static thay public static 3.7 Qui tắc đặt tên cho tham biến • Sử dụng cú pháp Lạc đà • Sử dụng tên mô tả tham biến Tên tham biến phải miêu tả đầy đủ, tên kiểu dùng để xác định nghĩa kịch • Sử dụng tên miêu tả theo nghĩa miêu tả theo kiểu Hạn chế sử dụng tham biên type-based cần thiết • Khơng sử dụng tham biến có sẵn Đây tham biến riêng • Khơng sử dụng tên tham biến theo cú pháp Hungari Ví dụ tên tham biến đúng: type GetType(typeName As string) string Format(string format, object args()) 3.8 Qui tắc đặt tên cho thuộc tính • Sử dụng danh từ cụm danh từ • Sử dụng cú pháp Pascal • Khơng sử dụng cú pháp Hungari Thuộc tính tạo phải có tên giống với kiểu bên Chằng hạn, thuộc tính Color, kiểu thuộc tính Color • Ví dụ cách đặt tên cho thuộc tính: public class SampleClass { public Color BackColor() { // Code for Get and Set accessors go here } } Ví dụ trình bày thuộc tính với tên giống kiểu public enum Color { //Insert code for Enum here } XDPM_Nhóm I(Phụ trách nhóm 8) Page public class Control { public Color Color() { get { //Insert code here } set { //Insert code here } } } Ví dụ sai thuộc tính Color mà kiểu Integer public enum Color { //Insert code for Enum here } public class Control { public int Color { get { //Insert code here } set { //Insert code here } } } 3.9 Qui tắc đặt tên biến Đặt tên biến miêu tả nội dung/mục đích sử dụng Tránh đặt tên biến với chữ cái, chẳng hạn i, t thay vào ta nên đặt tên index, temp Khơng viết tắt, ví dụ khơng viết num thay cho number Sử dụng danh từ cụm danh từ • Sử dụng cú pháp Lạc đà XDPM_Nhóm I(Phụ trách nhóm 8) Page • Sử dụng cú pháp Hungari cho kiểu nguyên thủy • Do not use Hungarian notation for scope of variables Sử dụng objCommand, objConn, param tên chuẩn cho SQLCommand SQLConnection, SQLParameter Sử dụng da tên cho SqlDataAdapter ad ds cho đối tượng DataSet • • Sử dụng i, j, k cho biến đếm Ví dụ cách đặt tên cho biến có kiểu liệu nguyên thủy C# Style name Common use style name Prefix Example sbyte SByte sbyt sbytSalary byte Byte byt bytRasterData short Int16 sht shtAge ushort UInt16 usht ushtAccount int Int32 int intQuantity uint UInt32 uint unitEmployeeID long Int64 lng lngQuantity ulong UInt64 ulng ulngDistance float Single flt fltTotal double Double dbl dblTolerance decimal Decimal dec decAmountOfMoney bool Boolean bln blnFound datetime DateTime dtm dtmStart char Char chr chrFirstLetter string String str strFName object Object obj objCurrent 3.10 Qui tắc đặt tên biến toàn cục Sử dụng kiểu Camel để đặt tên cho biến cục đối số hàm/phương thức: XDPM_Nhóm I(Phụ trách nhóm 8) Page 10 Control type Prefix Example the specific type is unknown) Data dat datBiblio Data-bound combo box cbo cboLanguage Data-bound grid grd grdQueryResult Data-bound list box lst lstJobType Data repeater drp drpLocation Date picker dtp dtpPublished Directory list box dir dirSource Drive list box drv drvTarget File list box fil filSource Flat scroll bar fsb fsbMove Form frm frmEntry Frame fra fraLanguage Gauge gau gauStatus Graph gra graRevenue Grid grd grdPrices Hierarchical flex grid flex flexOrders Horizontal scroll bar hsb hsbVolume Image img imgIcon Image combo Imgcbo imgcboProduct ImageList ils ilsAllIcons Label lbl lblHelpMessage Line lin linVertical List box lst lstPolicyCodes ListView lvw lvwHeadings Menu mnu mnuFileOpen Month view mvw mvwPeriod XDPM_Nhóm I(Phụ trách nhóm 8) Page 14 Control type Prefix Example MS Chart ch chSalesbyRegion MS Flex grid msg msgClients MS Tab mst mstFirst OLE container ole oleWorksheet Option button opt optGender Picture box pic picVGA Picture clip clp clpToolbar ProgressBar prg prgLoadFile Remote Data rd rdTitles RichTextBox rtf rtfReport Shape shp shpCircle Slider sld sldScale Spin spn spnPages StatusBar sta staDateTime SysInfo sys sysMonitor TabStrip tab tabOptions Text box txt txtLastName Timer tmr tmrAlarm Toolbar tlb tlbActions TreeView tre treOrganization UpDown upd updDirection Vertical scroll bar vsb vsbRate 3.13 Qui tắc đặt tên số Sử dụng kiểu viết hoa để đặt tên cho số Ví dụ: Const MIN_QUAL = 25 XDPM_Nhóm I(Phụ trách nhóm 8) Page 15 3.14 Qui tắc lớp kế thừa Attribute Sử Hậu tố lớp kế thừa từ Attribute Attribute: public class MyCustomAttribute: Attribute { ……………………………………… } 3.15 Qui tắc kế thừa Exception Sử Hậu tố lớp kế thừa từ Exception Exception: public class MyCustom Exception: Exception { ……………………………………… } 3.16 Qui tắc đặt tên hàm phương thức Sử dụng động từ cụm động từ Sử dụng cú pháp Pascal Ví dụ cách đặt tên cho phương thức: RemoveAll(); GetCharArray(); Invoke(); Đặt tên hàm/phương thức theo kiểu Động từ + Đối tượng (verbobject): public void ShowDialog() { base.ShowDialog(); } Hàm/phương thức có trả kết quả, tên đặt cho phải mô tả kết mà trả về: public string GetUserName() { XDPM_Nhóm I(Phụ trách nhóm 8) Page 16 string userName = string.Empty; return userName; } 3.17 Qui tắc đặt tên kiểu liệu Luôn sử dụng kiểu liệu gốc (Predefine type), không sử dụng kiểu đặt tên lại kiểu namespace "System": Được sử dụng Không sử dụng bool Boolean byte Byte double Double int Int32 object Object short Int16 string String XDPM_Nhóm I(Phụ trách nhóm 8) Page 17 Tránh khai báo kiểu liệu dạng "namespace"[".subnamespace.[ ]"]."kiểu liệu" cách sử dụng từ khóa using: -Tránh sử dụng: System.DateTime myBirthday; - Nên sử dụng: using namespace System; DateTime myBirthday; 3.18 Tránh để hàm trả giá trị boolean mệnh đề điều kiện, đặt biến cục kiểm tra vd : bool IsEverythingOk() { } //Tránh if(IsEverythingOk() { } //Đúng bool ok = IsEverythingOk(); if(ok) {} 3.19 Luôn sử dụng mảng 0; Trong tập hợp có mục(index), mục không 3.20 Luôn khởi tạo mảng reference type bẳng vịng lặp for Public class MyClass() XDPM_Nhóm I(Phụ trách nhóm 8) Page 18 {} Const int ArrarSize = 100; MyClass[] array = new MyClass[ArraySize]; For(int index = 0; index < array.Length; index++) { Array[index] = new MyClass[] } III QUI ƯỚC CODE FORMATS Qui ước Tab Sử dụng tab chèn vào đầu dịng code để định hình, không sử dụng khoảng trắng để thay tab Số lượng tab chèn vào đầu dịng code khơng nên Qui ước Block code Các Block code cấp phải tab Qui ước Khoảng cách Nên đặt khoảng cách sau dấu phẩy chấm phẩy VD: TestMethod(a, b, c); don't use : or: TestMethod(a,b,c) TestMethod( a, b, c ); Xung quanh toán tử VD: a = b; // don't use a=b; for (int i = 0; i < 10; ++i) don't use: or for (int i=0; i { enter + tab + [code] } VD: {//enter //tab sau code //code }//enter Tránh đặt nhiều class file Tránh có nhiều namespace file file nên kết hợp type vào namespace Tránh file có nhiều 500 dịng ( khơng bao gồm mã máy) Tránh phương thức có nhiều 200 dịng 10 Tránh phương thức có đối số 11 Một dịng khơng q 120 ký tự 12 Khơng nên tự sửa dòng mã máy  Nếu thay đổi mã máy, theo format style chuẩn code  Sử dụng từ khóa partial để chi lớp thành nhiều file giữ nhiệm vụ khác 13 Tránh ghi thích điểu hiển nhiên trog code Tự code nên giải thích code gọi tốt tên biến tên hàm rõ ràng, khơng cần giải thích 14 Văn dùng để giải thích giải thuật 15 Các câu lệnh lồng tối đa cấp Nếu lệnh phức tạp nên ngắt đặt biến chứa kết xử lí tiếp 16 Các vịng lặp đơn giản dùng biến i, j, k, l để đếm 17 Khi dùng so sánh biến với số nên viết số trước biến sau VD: if (2 == a) … XDPM_Nhóm I(Phụ trách nhóm 8) Page 21 18 Khi dùng lệnh switch ý có lệnh break case Nếu trường hợp đặc biệt ko có lệnh break phải thích cho người khác hiểu Dùng default cuối lệnh switch 19 Không truy cập hay thay đổi đối tượng nhiều lần biểu thức VD: v[i] = ++i; // wrong i = ++i + 1; // wrong 20 Không sử dụng câu lệnh lựa chọn (if, switch) thay nhiệm vụ đơn giản khởi tạo VD: bool pos; if (val > 0) { pos = true; } else { pos = false; } Viết lại  bool pos = (val > 0) ? true : false; Hoặc bool pos = (val > 0); 21 Exception Handling Chỉ ném ngoại lệ (thorw exception) tình đặc biệt Bắt trường hợp Exception cách cung cấp phương thức để trả trạng thái đối tượng Bắt Exception muốn bổ sung thông tin trả Messages cho người dùng biết 22 Đừng so sánh rõ ràng với true, false VD: if (conditison == false) //bad if(!condition) //good 23 Gán object = null để báo object khơng cịn cần thiết cải thiện nhớ 24 Mỗi dịng code khơng nên q dài Tối đa 80 kí tự Trường hợp dịng lệnh q dài thực ngắt xuống dịng: -Ngắt sau dấu phẩy -Ngắt sau toán tử -Ngắt sau kết thúc cấp VD: longMethodCall(expr1, expr2, expr3, expr4, expr5); BAD STYLE – AVOID: XDPM_Nhóm I(Phụ trách nhóm 8) PREFER: Page 22 var = a * b / (c - g + var = a * b / (c - g + f) + f) + * z; * z; IV CÀI ĐẶT PROJECT Thiết lặp project theo quy tắc sau: • Ln build project với cảnh báo mức Xem warning error Release build (cái mặc định VS.NET) • Mặc dù tùy chọn, chuẩn nói cảnh báo lỗi Debug build hay • Đừng chặn cảnh báo trình biên dịch • Ln ln rõ ràng hổ trợ chạy cấu hình file ứng dụng • Tránh phiên củ hướng kết hợp với CLR mã máy Tránh định nghĩa #define Sử dụng cài đặt file dự án đinh nghĩa cho soạn điều kiện thống • • Không đặt lập luận vào bên AssemblyInfo.cs • Khơng đặt mã máy bên file AssemblyInfo.cs • Định tất trường AssemblyInfo.cs tên ,mô tả, quyền • Tất hợp ngữ khác nên dùng thứ liên quan • Khơng nhận khác biệt mã máy • Tránh nhiều module mã máy Ln chạy code trạng thái mặc định, kiểm tra rõ ràng kiểm tra thao tác Tránh can thiệp với biệt lệ window (Debug|Exception) • Cố gắng đồng phiên tất mã máy máy khách giống ứng dụng logic • • Tránh khơng cho vào phương thức (#if…#endif) Dùng điều kiện phương thức thay public class MyClass { XDPM_Nhóm I(Phụ trách nhóm 8) Page 23 [Conditional("MySpecialCondition")] public void MyMethod() {} } • Tên ứng dụng VS.NET bạn file cấu hình App.Config, thêm vào project Chỉnh VS.NET có cấu trúc mặc định làm chuẩn project bạn , đồng hóa cấu trúc folder files cho project • • Liên kết tất thông tin solution-wide đến file chia sài chung: • Release build should contain debug symbols • Ln kí hiệu mã máy bạn, thêm vào ứng dụng chạy máy khách V MÔ TẢ CHI TIẾT FRAMEWORK Data Access • Ln quản lý truy cập database • Ln quản lý lập tập mức độ Không dùng Server Explorer để ngắt kết nối Windows form Tránh xác thực SQL Server Dùng xác thực window thay • • Chạy thành phần truy cập SQL Server ngăn cách từ client Luôn làm cho stored procedure bạn mức độ cao, kiểu lớp an toàn Chỉ lớp chứa stored procedure • Tránh đặt giá trị logic vào stored prodedure Nếu IF bên stored procedure, bạn làm sai • Security Ln địi hỏi độ mạnh tên bạn assemblies components quyền riêng ứng dụng public • XDPM_Nhóm I(Phụ trách nhóm 8) Page 24 public class PublicKeys { public const string MyCompany = "1234567894800000940000000602000000240000"+ "52534131000400000100010007D1FA57C4AED9F0"+ "A32E84AA0FAEFD0DE9E8FD6AEC8F87FB03766C83"+ "4C99921EB23BE79AD9D5DCC1DD9AD23613210290"+ "0B723CF980957FC4E177108FC607774F29E8320E"+ "92EA05ECE4E821C0A5EFE8F1645C4C0C93C1AB99"+ "285D622CAA652C1DFAD63D745D6F2DE5F17E5EAF"+ "0FC4963D261C8A12436518206DC093344D5AD293"; } [StrongNameIdentityPermission(SecurityAction.LinkDemand, PublicKey = PublicKeys.MyCompany)] public class MyClass {…} • ứng dụng mã hịa bảo mật file cấu hình ứng dụng bạn • khơng cho phép xem code, địi hịi cho phép tích hợp thay Trên server, triên khai sách bảo vệ co phép Microsoft,ECMA, với tên đủ tín nhiệm • [assembly:UIPermission(SecurityAction.RequestRefuse, Window=UIPermissionWindow.AllWindows)] • Ln set the principal policy in every Main() method to Windows XDPM_Nhóm I(Phụ trách nhóm 8) Page 25 ... Ví dụ, khơng có namespace Debug lớp Debug  Tránh sử dụng từ khóa Using namespace : namespace CodingStandardChecker; { using system = System; }  Gom tất namespace nhà cấp thành nhóm, namespace...STT I Thời Gian 21/03/2011 22/04/2011 13/05/2011 17/05/2011 Version 1.0 2.0 3.0 4.0 Nội Dung Hoàn thiện dần nội dung chuẩn mã nguồn Hoàn thiện dần nội dung chuẩn mã nguồn Hoàn