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:

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 意図の明白なインターフェース

Tài liệu tham khảo

Japanese

• Kevlin Henney『プログラマが知るべき９７のこと』
• ロバート C. マーチン 『Clean Code』
• Krzysztof Cwalina,Brad Abrams 『.NETのクラスライブラリ設計』
• アンドリュー・ハント/デビッド・トーマス『達人プログラマー』
• Dustin Boswell/Trevor Foucher『リーダブルコード』
• エリック・エバンス 『ドメイン駆動設計』
• Jaroslav Tulach 『APIデザインの極意』
• Namingのプレゼン資料

English

• 97 Things Every Programmer Should Know
• Clean Code: A Handbook of Agile Software Craftsmanship
• Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries (2nd Edition)
• The Pragmatic Programmer: From Journeyman to Master
• The Art of Readable Code (Theory in Practice)
• Domain-Driven Design: Tackling Complexity in the Heart of Software
• Practical API Design: Confessions of a Java Framework Architect