Naming - Cách đặt tên

Bài đăng này đã không được cập nhật trong 2 năm

Bài viết được dịch từ bài Naming -名前付け- của tác giả Koki-jp trên Qiita

Naming - Cách đặt tên

Một trong những kĩ năng quan trọng của lập trình đó là đặt tên Và, cái này cũng có liên quan đến cảm nhận cũng như sự tinh tế của từng người nên để có thể thành thạo được kĩ năng này cũng là một việc khó Ở bài viết này, tôi đã tổng hợp các tài liệu liên quan đến việc đặt tên và tổng hợp lại, mọi người cùng xem nhé.

Sự quan trọng của việc đặt tên

ソフトウェアの設計のアプローチとして、『まず名前から入る』というのは、あまり語られていない秘訣としてもっと広く知られても良いように思います。

(As a software design approach, I think, widely unknown secret "First, enter the name " must be talked more)

Matsumoto Yukihiro - 97 Things Every Programmer Should Know

Sự cơ bản của việc giao tiếp

Tên gọi là cơ sở của việc giao tiếp. Nếu tôi và bạn đều không có tên thì khó mà có thể hiểu rõ được nhau Để tên gọi có thể trở thành cơ sở của việc giao tiếp thì cần theo những quy tắc sau:

Có thể phát âm được
Có thể tìm kiếm được

※ Nếu chỉ trong thế giới hiện tại thì có thể ko cần tìm kiếm được cũng được. Việc lập trình thường do team hoặc do nhiều người tiến hành. Do là công cụ dùng trong việc giao tiếp nên nếu tên không phát âm, không tìm kiêm được thì sẽ là sự bất tiện cực kì lớn, khi đó hiệu suất công việc cũng sẽ thay đổi.

ある会社でgenymdhmsという名前を使っていました。このため、「ジェンワイエムディーエイチエムエス」といいながら仕事をする必要がありました。

(There is a company, use the name genymdhms. For this reason, there is a need to say "Gen Wai Em Dee H. Em Es" while working)

Robert C. Martin - Clean Code

Guide line

Không sử dụng hệ thống kí pháp Hungary

Nếu muốn đặt tên có thể phát âm được thì không nên sử dụng hệ thống kí pháp Hungary (Hungary Notation). Kí pháp Hungary và hệ thống Hungary là khác nhau nên cần phải chú ý. Tài liệu về hệ thống Hungary thì các bạn có thể đọc tại link sau Making Wrong Code Look Wrong

Không sử dụng chữ viết tắt và từ viết tắt từ các chữ đầu của từ khác

一般的に、識別子に略語または頭字語を使用してはいけません。名前については簡潔さよりも読みやすさのほうが重要です。一般的に理解されていない略語および頭字語を使用しないことも同様に重要です。すなわち、ある分野におけるエキスパートではない大多数の人々は、それが何を意味するのかすぐにはわからないのです。

Krzysztof Cwalina,Brad Abrams - Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries

Ví dụ như UI, XML được sử dụng rộng rãi. Tuy nhiên, nếu viết các từ này ở trong code thì cũng không là nguyên nhân gây ảnh hưởng đến khả năng lý giải code. Ở trong cuốn sahcs Coding Guideline for Cocoa của Apple có tổng hợp lại danh sách các từ viết tắt nên dùng Acceptable Abbreviations and Acronyms

Ở trong thư viện các Class của Objective-C được Apple công khai thì các Class đều có gắn kèm tiền tố (Prefix) . Ví dụ như UIView, NSString. Đây là do Objective-C không có namespace nên bắt buộc phải thêm vào.（※ Tiện đây thì "NS" là viết tắt của "NeXTSTEP")

Cần có quy tắc khi nào sử dụng chữ hoa và chữ thường

Để có thể tìm kiếm được thì việc phân biệt sử dụng giữa chữ hoa và chữ thường là quan trọng và cần thiết. Về việc các sử dụng chữ hoa và chữ thường thì các bạn có thể tham khảo tài liệu rất hữu ích sau MSDN

Code Naming

Ngôn ngữ Ubiquitous / Ngôn ngữ chuyên dụng

Ở bên trong code, đặc biệt khi có chia thành các tầng model thì nên sử dụng Ngôn ngữ Ubiquitous. Không suy nghĩ về phạm vi của domain và chương trình. Không làm cho chương trình trở nên quá tách biệt là một việc quan trọng. Nếu suy nghĩ chương trình làm gì, có mục đích gì thì tự nhiên model sẽ trở nên tốt hơn. Các suy nghĩ này thì ở những người lập trình giàu kinh nghiệm gọi là "Ngôn ngữ chuyên môn"

常にアプリケーション領域のボキャブラリーを使ったコード記述を試みましょう。-中略-さらにこれを推し進めれば、アプリケーション領域のボキャブラリー、シンタックス、セマンティックスーつまり専用の言語を用いて実際にプログラムを行うこともできるのです。

Andrew Hunt / David Thomas - The Pragmatic Programmer

Tên class là danh từ và động danh từ

Về cơ bản thì tên class là danh từ. Ở trong thiết kế Domain-driven thì sẽ xuất hiện pattern dịch vụ (Services). Việc này rất tiện dùng. Tuy rằng không phải là ngôn ngữ Ubiquitous nhưng các phần xử lý chung thì khi làm app kiểu gì cũng sẽ xuất hiện. Ví dụ như CSV parser, hay ở Windows là Registry Accessor Những phần này thì khi đặt tên chúng ta sẽ thêm Service vào đằng sau. Đặt tên là CSVParser cũng được rồi nhưng CSVParingService sẽ cho cảm giác tốt hơn.

RegistoryAccessor thì sao ? "Accessor" có vẻ không được dùng phổ biến lắm thì phải. Trong những trường hợp như thế thì đặt là RegistoryAccessingService, RegistoryService có nhiệm vụ accessing cũng OK đấy chứ.

Nếu không thêm được vai trò vào tên thì hãy chuyển nó thành động từ rồi thêm Service vào cuối thì tên sẽ cool hơn (cười)

Tên method bắt đầu bằng động từ

Cái này rất là nổi tiếng đấy. 「メソッドはそのオブジェクトに命令を下すもの」 (method là nơi thực hiện những mệnh lệnh của đối tượng) nên dùng thể mệnh lệnh thì tốt hơn. Do đó tên cần bắt đầu ngay bằng động từ. Danh sách sau có cover hầu hết các trường hợp:

Động từ	Ý nghĩa	Giá trị trả về chính
Get	Lấy ra	Object
Set	Đặt giá trị	void
Update	Cập nhật	void( hoặc số lượng đã update)
Delete	Xóa bỏ	void( hoặc số lượng đã delete)
Insert	Chèn vào	void
Select	Lựa chọn	Object
Find	Lựa chọn	Object
Add	Thêm vào	void
Remove	Xóa bỏ	Object
Clear	Dọn sạch	void
Append	Viết thêm	void or Object sau khi đã thêm
Trim	Chỉnh sửa	Object
Compare	So sánh	Kết quả so sánh(-1,0,1)
Concat	Nối thêm	Object
Split	Phân chia	Object
Enumerate	Liệt kê	Array
Move	Di chuyển	void
Copy	Sao chép	void
Create	Tạo thành	Object
Make	Tạo thành	Object
Generate	Tạo thành	Object
New	Tạo mới	Object
Build	Xây dựng	Object
Flush	Flush	void
Begin	Bắt đầu	void
End	Kết thúc	void
Initialize	Khởi tạo	void
Load	Load	void
Merge	Ghép	Object
Read	Đọc	Object
Write	Viết	void
To	Biến đổi	Object
Convert	Biến đổi	Object
Accept	Cho phép	void
Fill	Làm đầy, điền	void
Apply	Áp dụng	void
Show	Hiển thị	void
Union	Hợp của tập hợp	Object
Intersect	Giao của tập hợp	Object
Do	Tiến hành	void
Run	Tiến hành	void
Shutdown	Tắt	void
Save	Lưu lại	void
Cancel	Hủy bỏ	void
Refresh	Làm mới	void
Execute	Tiến hành	bool(Thành công hay thất bại)
Resolve	Giải quyết	Object
Invoke	Gọi ra	Object
Handle	Xử lý	Object
Raise	Gọi ra	void
Is	Có phải là ... không ?	bool
Contains	Có chứa ... không ?	bool
Exists	Có tồn tại không ?	bool
Verify	Xác nhận / Đánh giá	bool(nếu để là void không được thì trả về ngoại lệ cũng tốt)
Validate	Kiểm chứng	bool
Try	Thử	bool(nếu để là void không được thì trả về ngoại lệ cũng tốt)
Has	Có ... không	bool
Equals	So sánh	bool
Can	Có thể không	bool

Tên mà không thể hiện được bản chất thì không phải là tên tốt. Tên method là Get nhưng bên trong lại thực hiện Set thì rõ ràng là không đúng rồi.

Tên của method thể hiện xử lý cơ bản bên trong của nó

Đây là kĩ thuật mà gần đây tôi mới được biết, nhìn vào các hệ thống open source sẽ thấy kĩ thuật này rất hay được dùng. Ví dụ như Ở .NET, có method tên là CreateDirectory. Nếu ta wrap cái method này, tạo method nếu chưa tồn tại thư mục thì tạo thì nó sẽ có tên như sau CreateDirectoryIfNotExists, có vẻ rất tiếng Anh đúng không. À mà nếu dài quá thì ...

Guide line liên quan đến việc đặt tên trong code

Về việc đặt tên cơ bản thì có thể tham khảo tài liệu sau MSDN Thêm nữa, đây là một tài liệu dễ hiểu khác bằng tiếng Nhật Okapi. , có danh sách các method trả về boolean. The Art of Readable Code cũng ít trang, có thể đem bên mình được, tuy nhiên tranh minh họa thì tôi không thích lắm.

Interface rõ ràng minh bạch

ある開発者があるコンポーネントを使用するために、その実装についてじっくり考えなければならないのであれば、カプセル化の価値は失われる。

Eric J. Evans - Domain-driven design

Cần có những Interface mà không cần biết cụ thể bên trong nó làm những gì nhưng vẫn có thể sử dụng thoái mái dựa vào hình dáng của method・tên・tham số. Tác giả Eric J. Evans có giới thiệu vấn đề này tại đây 意図の明白なインターフェース