找回密碼
 注冊帳號

掃一掃,訪問微社區

涼鞋同學 Unity 游戲框架搭建 2018(七)命名的力量:變量

0
回復
109
查看
打印 上一主題 下一主題
[ 復制鏈接 ]
排名
2324
昨日變化

63

主題

508

帖子

2429

積分

Rank: 9Rank: 9Rank: 9

UID
148923
好友
66
蠻牛幣
2598
威望
0
注冊時間
2016-5-17
在線時間
836 小時
最后登錄
2020-3-31

專欄作家

QQ

馬上注冊,結交更多好友,享用更多功能,讓你輕松玩轉社區。

您需要 登錄 才可以下載或查看,沒有帳號?注冊帳號

x
變量的命名入門
大家先來試著理解一下這段代碼:
[C#] 純文本查看 復制代碼
var todoList = new TodoList();
todoList.Todos = new List<Todo>();

var todo = new Todo() { Id = 0, Finished = false, Content = "測試" };

todoList.Todos.Add(todo)

todo.Finished = true;

代碼本身很簡單,就算不用去看 TodoList 類和 Todo 類的定義,也是可以讀懂以上代碼的。
那這是如何做到的呢?
答案就是:進行合適的命名。
而達到以上代碼的效果的主要是變量的命名。
因為以上出現的類都是 Model 類,而 Model 則是用來描述業務是什么,而 Model 類中大部分代碼則是變量。
比如 這是一個 TodoList App (待辦事項),其中:
  • 有待辦事項列表
  • 待辦事項列表有待辦事項
  • 待辦事項可以完成和未完成。
  • 待辦事項可以編輯文本。

以上幾點一般是我們接收到任務并理解業務之后梳理出來的。如果設計成代碼結構,結構大致如下:
  • 待辦事項列表
    • 待辦事項
      • 完成/未完成
      • 文本



很自然 Model 的代碼就寫出來了,代碼如下。
TodoList.cs
[C#] 純文本查看 復制代碼
public class TodoList
{
    public List<Todo> Todos;
}

Todo.cs
[C#] 純文本查看 復制代碼
public class Todo
{
    public int Id;

    public bool Finished;

    public string Content;

}

為了讓以上類更容易地在其他文件中理解,筆者在命名上做了哪些工作呢?
TodoList 類中的 Todos 變量:
  • Todos 是復數,說明其類型可能是數組、List 或者其他的集合。   
  • Todos 首字母大寫,說明訪問權限是 public 類型的。   
  • Todos 名字本身是一個名詞,解釋成中文則是:要做的事(待辦事項),本身準確地傳達了變量的意思。   

Todo 類
  • Id,和 Todos 一樣,傳達了訪問權限,和意思(標識),但是沒有傳達其類型。不過,不管是 int 還是 string 都無所謂。   
  • Finished,也是一樣的,public 權限、意思(完成了)。同樣也沒有傳達其類型,不過這里可以這樣理解,Finish 是動詞,加上 ed 則是過去式,有時態說明有狀態,這個狀態只有兩個,完成和未完成,所以是 bool 類型,這是筆者的一個習慣,當然也可以命名為 IsFinish,等等。   
  • Content,中文意思是內容,也就是文本內容,一般為 string 類型,因為首字母大寫,所以也是 public 權限。   

簡單幾行代碼,就可以傳達這么多信息,所以 命名是一門藝術
小結
在對一個變量進行命名的時候,無非要思考以下三點:
  • 描述
  • 權限
  • 類型

權限和類型的表達很容易,因為關于這方面的方法論(套路)是固定的,可以很容易掌握的。
比較考驗功底的是變量的描述,是需要長期進行訓練的。
描述、權限、類型
接下來以這三點為主,分別進行方法論的介紹。
先從最簡單的來,最簡單的則是 權限 的表達
權限
權限指的是訪問權限,在 C# 中有 public、private、protected、internal 類型。
這里在進行變量命名時分為兩種。
  • 可外部訪問的 public 和 internal。
  • 和不可被外部訪問的 private 和 protected。

權限的表達,筆者自己的習慣是,可被外部訪問的變量采用首字母大寫。
比如:
[C#] 純文本查看 復制代碼
public string Name;
internal static int ReferenceCount;

而不可被外部訪問的變量采用 m 前綴。
比如:
[C#] 純文本查看 復制代碼
private string mShowedText;
protected int mMgrId;

這是筆者長期的一個習慣,也是筆者自己維護的 QFramework 的命名規范。
所以關于權限的表達非常簡單,依靠代碼規范就能搞定了,規范怎么定就怎么用。
這一點是最最最容易達到的。
如果各位還沒有開始在意命名這件事情,從權限開始上手是最容易的。
類型
變量是有類型的,最好呢是把類型能夠表達出來。
類型的表達,當然這也可以依照某些代碼規范來解決的。
比如匈牙利式的代碼規范:
[C#] 純文本查看 復制代碼
private int m_nAge;   // n 代表數量
private string m_strName // str 代表 string

不過這種規范需要適應一段時間,這里筆者不太推薦新手用這種規范解決類型表達問題
而是采用一種比較簡潔、優雅的方式,來表達變量的類型。
比如:
[C#] 純文本查看 復制代碼
public int Age;

Age 年齡,很容易想到是 int 類型。
[C#] 純文本查看 復制代碼
public int Age;

Name 名字很容易想到是 string 類型。
[C#] 純文本查看 復制代碼
public int PetCount;
public int PetNumber;

寵物數量,很容易想到是 int 類型。
[C#] 純文本查看 復制代碼
public bool Completed;

Completed 完成了,是 bool 類型。
而這部分的詳細內容會在接下來的一個小節中詳細介紹。
描述
關于變量的描述的內容就比較多了,但是原則很簡單,就兩個字:準確。
  
為變量命名時最重要的考慮事項是,該名字要完全、準確地描述出該變量所代表的事物。——《代碼大全》
如何達到準確呢?這部分也會在接下來的一個小節中介紹。
在本小節,先給大家對變量所用的詞類型進行簡單的分類:
  • 事物
    • string
      • Name
      • NickName

    • int
      • Age
      • XXXCount
      • Times



  • 狀態
    • 過去式
      • Finished

    • 進行時
      • Waiting

    • 一些不推薦使用的(IsXXX):
      • IsFinished
      • IsFinish
      • IsWaiting

    • 形容詞
      • active


  • 其他
    • C# 中特有的 委托、事件 等。
      • OnXXXFinished
      • OnBeforeDestroy
      • OnLoadDone
      • OnLoadStart



所以在之后詳細講述變量的描述表達部分會根據這三點來進行介紹。
小結
讀者讀到這里,權限的表達是最容易做到的,如果沒有意識到的童鞋們,可以在工作中開始權限的表達訓練了。
權限的表達比較適合作為變量名訓練的的第一步。
關于權限部分的內容就到此完結了,下文中不再贅述。
而剩下的類型和描述用兩個大章節進行詳細介紹。
我們先搞定相對較容易的類型的表達,這樣好讓大家掌握并快速在工作中實踐。
類型的表達關于集合(List、Array、Dictionary 等等)
List、Array 可以使用名詞的復數來搞定。
比如:
[C#] 純文本查看 復制代碼
var todos = new List<Todo>();
var todos = new Todo[]{};

也可以將集合類型作為后綴表達
[C#] 純文本查看 復制代碼
var todoList = new List<Todo>();
var todoArray = new List<Todo>();

Dictionary
因為是 key-value 類型的集合,可以使用 xxx4yyy方式命名(4 = for),這是筆者個人習慣,不強制。
[C#] 純文本查看 復制代碼
var todo4Id = new Dictionary<string,Todo>();

也可以使用類型作為后綴。
[C#] 純文本查看 復制代碼
var todoDict = new Dictionary<string,Todo>();

但是 key-value 類型使用 類型作為后綴表達效果較差,所以推薦 xxx4yyy 方式。
其他的集合類型,比如 Queue、Stack 等,也同樣可以采用類型后綴的方式。
[C#] 純文本查看 復制代碼
var panelStack = new Stack<UIPanel>();
var msgQueue = new Queue<Msg>();

Stack 和 Queue 是技術概念,所以一般會在框架/插件/工具層使用,在業務層使用得較少。
集合類型部分介紹到這里。
數值/數據類型、string/char 等 (事物)數值類型(int/flout/double):
int 類型常見的后綴詞(限定詞):
Number
[C#] 純文本查看 復制代碼
var todoNumber = todos.Length;

Index
[C#] 純文本查看 復制代碼
var todoIndex = todos.IndexOf(todo);

Count
[C#] 純文本查看 復制代碼
var todoCount = todos.Count;

int 類型常見的前綴詞:
num
[C#] 純文本查看 復制代碼
var numTodos = todos.Length;  // number of todos 縮寫,不太常用。

float/double 類型常見的后綴詞
Average、Sum 等。
[C#] 純文本查看 復制代碼
var ageAverage = ageSum / peopleCount;

這種類型的后綴詞和前綴詞在計算時經常會用到。
這里叫做計算限定詞。
下面列出常用的計算限定詞:
[C#] 純文本查看 復制代碼
Count、Number、Num、Index、Total、Sum、Average、Max、Min、Record 等。

《代碼大全》建議,除了 Num 之外其他的都建議放到后綴
還有一些數值類型的名字本身就表達了其類型。
[C#] 純文本查看 復制代碼
age(int)、times(int) 等。

數據類型(string/char):
數據類型沒什么好說的,只能盡量選取名字本身就表達其類型的這種名字,而這部分的內容算是描述的表達部分,這里先列出一部分:
username(string)、password(string)、name(string)、content(string)、title(string)、description(string)、id(int/string) 等。
bool、枚舉(狀態)bool 類型:
  • 使用動詞 + 時態。
    • done
    • finished
    • completed
    • updating
    • enabled

  • 使用 Is  + 名詞。
    • isEnemy

  • 形容詞
    • active


給 bool 類型取名的原則很簡單,只要表示其狀態只有兩種就好。
比如 GameObject 要么為 激活狀態 (active 為 true) ,要么為 未激活狀態 (active 為 false)。符合這樣的就是一個很好的 bool 變量名,不可能有第三個狀態的。
再比如,一個任務要么完成(finished 為 true),要么為未完成(finished 為 false)。
枚舉
枚舉部分要分兩個部分講,一個是定義部分,一個是變量部分。
枚舉的定義:
[C#] 純文本查看 復制代碼
// 事件
public enum UIMainPanelEvent
{
    // 事件監聽
    OnModelDataChanged,

    // 指令 (動賓短語、動詞)
    UpdateView
}

// 狀態 (與 bool 類型一樣)
public enum ResLoadState
{
    LoadBegan,
    Loading,
    LoadEnded,
}

// 結果 (名詞、形容詞)
public enum ResLoadResult
{
    Success,
    Fail,
}

定義部分和 bool 類型很像,比如 ModelDataChanged 就是 動詞 + 時態的方式。
Unity 特有的 GameObject、Transform、Button、Image 等
[C#] 純文本查看 復制代碼
GameObject heroObj;
GameObject heroGameObj;
Transform  heroTrans;
Button btnEnterMainPanel;
Image logoImage;

以上為常見的前綴、和后綴。
關于類型的表達介紹就到這里。
小結
到這里我們對類型的表達進行了詳盡的介紹。
筆者關于類型表達的方法論也都全部介紹完了,大家可以筆者的方法論為準進行練習,在此基礎上進行不斷思考改進稱為自己的方法論。
  
思考什么呢?
思考如何讓別人(或自己)在別的文件中使用變量就能猜到其類型呢?
所以筆者介紹的方法論不是重點也不是權威,重點是不斷進行思考。
描述的表達
終于到了重頭戲了。
描述的表達是能夠考驗一個開發者功底的工作。
對于 Model 類的變量命名。
  • 要想有一個好的描述,必須非常了解業務的。
  • 因為只有非常了解業務了,才能找到非常準確的描述。

就像本 Chat 的開頭的入門那樣:
  • 業務最起碼應該是梳理過一次的,梳理成自己能理解。
  • 梳理過一次之后要再進行一次結構化的梳理,這樣比較好轉化為代碼。
  • 結構化梳理之后才能定義 Model 類和其變量。

以上對各位的要求會比較高,所以筆者這里建議,大家熟練掌握了了權限和類型的表達后在進行描述的練習。
而在這之前,本 Chat 也只是介紹了 Model 的變量命名。
這是因為 Model 的變量定義是相對容易的。但是我們的工作不只有定義 Model,還有好多其他的類需要我們定義,而定義類多少要定義一些變量。而本 Chat 不能覆蓋所有的變量命名場景,所以會給出一些準則和練習步驟來給大家參考。
練習步驟一: 代碼部分全部為英文。
在 Unity 中少數的需要顯示在編輯器上提供參數調整的變量可以用一些中文漢字。而剩余的最好是全部使用英文。
這里最好是在編碼時隨手備著一個查詞軟件,可以通過鍵盤快捷鍵快速查詢的。要養成這個習慣。到最好發現,在某一個領域或某種業務常用的詞匯就那些,自己都記住了,很少會再編碼時使用查詞軟件。
練習步驟二: 業務命名而不是技術命名
這個標題是筆者自己理解的,《代碼大全》的描述是變量名應該描述的是 what 而不是 how。也就是變量是什么而不是怎么做。
因為業務概念是現實的模擬,而技術概念只是手段。所以筆者理解為為了業務命名而不是為技術命名。
要理解此準則非常簡單。摘抄《代碼大全》的一段話給大家理解:
  
一個好記的名字反映的通常都是問題,而不是解決方案。一個好名字通常表達的是“什么”(what),而不是“如何”(how)。一般而言,如果一個名字反映了計算的某些方面而不是問題本身,那么它反映的就是“how”而非“what”了。請避免選取這樣的名字,而應該在名字中反映出問題本身。
  
一條員工數據記錄可以稱作 inputRecord 或者 employeeData。inputRecord 是一個反映輸入、記錄這些計算概念的計算機術語。employeeData 則指的是問題領域,與計算世界無關。與此類似,對一個用于表示打印狀態的位域來說,bitFlag 就要比 printerReady 更具計算機特征。在財務軟件里,calculateValue 的計算痕跡(how) 也要比 sum (what) 明顯。
書中原文解釋的很清楚了,不再多說了。
練習步驟三:分清楚何時用技術命名
這里要說一點注意的,要分清楚在哪個層。舉一個筆者框架中的 SerializeHelper (序列化器),序列化是技術概念,是“怎么做?” (how),但是它可以做游戲數據的存儲等操作。那么它為什么不叫做 DataSaver/DataLoader 這些名字呢?
這是因為 SerializeHelper 這個類不在業務層,而是在框架層。框架本身提供的更多的是工具。
小結
練習步驟給出了 1、2、3,很容易上手,命名這件事本身比較容易掌握,難得是初學者非常不在意。老手呢一般趟坑躺多了自然就會意識到。而初學者再去趟一下這些坑有點浪費時間,不如一開始就意識到命名這件事的重要性。
到此呢,權限、類型、描述的練習步驟和原則(準則)都給了。接下來簡單聊聊,為什么要命名和如何更容易地落實命名這件事到工作中呢?
為什么要命名?
代碼的本質是信息,其承載著信息,這個信息可以被編譯器理解,也要被人理解。
首先你,代碼要被編譯器理解,這是最基本的要求,也代表著開發者能和計算機溝通,讓計算機幫忙處理任務。
其次呢,是要被人理解。
這些人可能是:
  • 自己(日常)
    • 與自己朝夕相處時間最長的就是這些代碼了,如果代碼非常容易讀懂并且整潔,每天的工作狀態都會不一樣。
    • 在 debug 時候,還是要去讀代碼的,好的代碼是更容易被閱讀的,容易被閱讀 debug 所花費的時間就會減少。
    • 增加功能,也還是一樣需要閱讀代碼的,以上同理。
    • 使自己對項目的理解更深刻、清晰。


  • 同事(協作)
    • 同樣代碼被容易閱讀,同事的效率也有所提升,也會得到同事的認可,

  • leader(晉升)
    • 很多團隊有代碼 review 的文化,好的代碼更容易獲得上級和同事的認可。
    • 得到同事和上級的認可,晉升就是很自然的事情了。

  • 來接手項目的人(離職)
    • 離職的時間也會被節省,不會被拖著問這是什么那是什么。

  • 所有開發者(開源)
    • 節省非常多人的時間,時間就是生命。

  • 讀者(教學,正在讀本 chat 的各位則是這個范圍的)

最終受益最多的還是自己,而投入的只不過每個變量多花費了幾秒的思考時間而已。
總之協作這個詞有一個協字,可以理解成妥協的協,也可以理解成協助的協。
給變量合適的命名既是一種妥協也是一種協助。
這就是為什么筆者單開一個 chat 來寫一個大家認為如此簡單的事情。
如何落地變量的命名
單寫這一小節是希望大家不是只讀一讀這篇 chat 就完事了,而是要把變量的命名這件事情落實到自己產出的代碼上去。
在工作中養成一個習慣的阻礙有很多。
最常見的原因就是項目時間緊。
這個問題很好解決,只要訓練的時機根據實際情況進行調整就好了。
對于初學者或者項目非常緊急的開發者,在第一遍寫邏輯的時候,變量可以先隨便命名(按照自己的習慣),但是只要當前的測試點驗證通過或者功能點完成,就應該回過頭把變量的名字好好想下,進行重新命名。一般 IDE 都帶重構功能,只要改一個地方,其他代碼部分會全部跟著更改。
這樣做的目的是為了防止同一時間做兩件事情。
  • 邏輯編寫
  • 變量命名

對于命名新手來說,同一時間做兩件事情會很吃力。
本身邏輯編寫就很吃力了,再加上需要思考的變量命名,會更加吃力。
所以對于命名新手要求同一時間只思考一件事情。
對于時間非常緊急的開發者,如果進行命名的思考會影響項目的進度,那還是等項目不急的時候再落實就好了。
只要能做到,在進行邏輯編寫時,只考慮如何完成或者如何實現就好了。
在變量命名時,只專注于如何取個合適的名字,只考慮變量的描述、類型、權限就好。
如下:
  • 變量的命名是否準確描述?
  • 變量的命名是否表達了類型?
  • 變量的命名是否表示了權限?

這樣堅持一段時間后,就能做到同一時間就可以做兩件事情。
初學者們只要記住一點就夠了:
  • 合適的命名可以不在創建變量的時候完成。

但是最終目標還是將進行合適的命名這件事情養成習慣,在創建變量的同時就已經為變量取了一個非常合適的名字。
最后,非常感謝 QFramework 的 邊上海 邊前輩對此專欄的勘誤和提供的一些非常有價值的建議。
更多內容
  • QFramework 地址:https://github.com/liangxiegame/QFramework
  • QQ 交流群:623597263
  • Unity 進階小班

    • 主要訓練內容:
      • 框架搭建訓練(第一年)
      • 跟著案例學 Shader(第一年)
      • 副業的孵化(第二年、第三年)

    • 權益、授課形式等具體詳情請查看《小班產品手冊》:https://liangxiegame.com/master/intro

  • 關注公眾號:liangxiegame 獲取第一時間更新通知及更多的免費內容。



回復

使用道具 舉報

您需要登錄后才可以回帖 登錄 | 注冊帳號

本版積分規則

神马电影34pp影视午夜