了解 VB 官方约定指南中发现的矛盾

Question

我希望其他成员可以帮助我理解以下六个相互矛盾的准则：

a) 名称长度：

建议缩写...

对于长 [...] 术语，使用缩写来保持名称长度 合理。

Source

建议不要缩写：

请勿在标识符名称中使用缩写或缩略词。

Source

它是什么？签约还是不签约？ PromotionalNumberTextBox 还是 PromNumTextBox？

b) 事件处理程序名称：

以描述事件类型的名词开头的事件处理程序名称 后跟“EventHandler”后缀，如“MouseEventHandler”。

Source

Thia 与 Visual Studio 自动生成的内容不对应。请参阅下面的Button1_Click事件处理程序，它遵循控件、下划线和事件的格式。

编辑：其实并不矛盾。有关解释，请参阅 jmcilhinney 的评论。

Private Sub Button1_Click(sender As Object, e As EventArgs) Handles Button1.Click
    '... 
End Sub

c) 匈牙利符号：

不要使用匈牙利符号。

Source

...但以下两个似乎都是匈牙利符号的变体。

对象应该使用一致的前缀来命名 很容易识别对象的类型。 [...] chkReadOnly [...] lblHelpMessage

Source

使用 [...] 前缀表示变量的数据类型。 [...] 数量

Source

d) 首字母大写：

对于长 [...] 术语，请使用缩写 [...] 例如，“HTML”， 而不是“超文本标记语言”。

Source

[...] PascalCasing [...] 表示长度超过两个字母的 [...] 首字母缩略词 [...] 示例：[...] HtmlTag"。

Source

这是模棱两可的。假设我有首字母缩写词 PIN。应该是PINTextBox还是PinTextBox？

e) 评论：

将 cmets 放在单独的一行而不是放在一行的末尾 代码。

Source

注释可以跟在同一行的语句之后，也可以占据整个 行。

Source

这是模棱两可的。是否推荐使用内联 cmets？

f) 星号行分隔符：

不要用格式化的星号块包围 cmets。

Source 但是，还提供了以下使用格式化块星号的示例：

'*****************************************************
' Purpose:   Locates the first occurrence of a
'            specified user in the UserList array.
' Inputs:
'   strUserList():   the list of users to be searched.
'   strTargetUser:   the name of the user to search for.
' Returns:   The index of the first occurrence of the
'            rsTargetUser in the rasUserList array.
'            If target user is not found, return -1.
'*****************************************************

Source

Answer 1

以下是我的建议：

名称长度

从“干净代码”的角度来看，变量名应该是intention revealing。我希望任何阅读我的代码的人都清楚变量的用途，因此请使用描述性名称，而不是使用读者可能不知道的缩写。

事件处理程序名称

当您使用 Visual Basic 框架生成事件处理程序名称时，我将使用 Visual Basic 的约定。

但是，与其选择使用生成的默认事件处理程序名称，不如按照一般命名约定的建议，在方法名称中添加更多信息，以便读者确切地知道它的作用，例如例如，使用“SaveButton_Click”代替“Button1_Click”。

匈牙利符号

Hungarian notation 通常不需要，因为通过在现代 IDE 中检查变量类型很容易查看变量类型，例如ItemCount 会比 intItemCount 更好；添加缩写描述符只会添加“噪音”。

但是，变量名称仍应能显示意图，因此我将使用 PriceGrid 代替 grdPrices（例如）。这种方法的好处意味着代码也可以被所有人理解，即他们不需要知道 VB 前缀缩写的含义。

首字母大写

首字母缩写词应大写。

使用此约定，读者会立即知道全部大写的单词是首字母缩略词。例如，在您的场景中，如果您使用“PinTextBox”，您是指用于支撑、固定或连接东西的细长金属的文本框，还是个人识别码（即 PIN）？

评论

编写良好的代码应该是自记录的，因此不需要 cmets。 然而如果您需要记录为什么使用了一段深奥/不明显的代码，建议使用 cmets。

当您必须添加注释时，将其放在代码上方的单独行中效果很好，因为读者必须先阅读注释，然后才能遇到您要突出显示的代码。

星号行分隔符

如果 VB 框架自动生成带有星号的文件头，那么您就可以使用它。然而，没有星号的评论块效果更好，因为在实践中你会发现有时文本太多，评论在星号之外流动。如果去掉星号，它看起来更整洁。

Answer 2

可行约定是当一个人或另一个人即时理解代码的每个单词时。尤其是您的同事或取决于您雇主的要求。

---

a) 长名称。

读长名容易吗？不 ！使用最少的字符找到最明确的含义。 或者使用另一种编码方法：Object.Property/将你的方法分成几个

Sub ReturnLeftCup_SwapWithNext_ReturnEveryCups(...)
    ' ...

' Prefer
Sub ManipulateCups(...)
    ReturnLeftCup(...)
    SwapCupWithNext(...)
    ReturnAllCups(...)
End Sub

---

b) EvenHandler 后缀。

我的理解是这并不矛盾：

• 写入事件处理程序名称/含义/操作：ButtonClick 或 Button_Click
• 不要写“EventHandler”：ButtonClickEventHandler 或 ButtonClick_EventHandler

字符串“EventHandler”被自动附加到在 VB6 IDE 中处理事件的方法中，即使事件名称 (Click/Enter) 也已明确附加。

---

c) 匈牙利符号：

要在整个解决方案中查找每个 TextBox，可以很容易地使用搜索工具或智能感知来查找文本：

• “文本框_”
• “TBox_”
• “TBX_”
• ...

如果省略前缀，我将不得不列出任何 TBox 的名称，然后一一搜索...

顺便说一句，如果你有一个标签、一个文本框和一个与客户验证表单相关的按钮。

Private Sub ClickCustommer(...) Handles bCustommer.Click
    lCustommer.Text = tCustommer.Text.ToUpper()
End Sub
' :/ bCustommer is a Button obviously.
' but are lCustommer and/or tCustommer controls or objects ?

Private Sub Button_Custommer_Click(...) Handles ButtonCustommer.Click
    Label_Custommer.Text = TextBox_Custommer.Text.ToUpper()
End Sub
' better don't you think ?

控件使用前缀，变量/对象（非控件）不使用前缀

前缀（如TextB_User）或后缀（如User_TextB）？

注意！个人意见：

很久以前使用的前缀。然后改变了主意……然后又改变了主意：/

如果你使用后缀，你的 Form 控件在 IDE 的控件列表 DropdownList 中不是按类型排序的。当您忘记将按钮放在面板内的面板内时，您已将按钮放在 splittercontainer 内的标签页内 .... 全部停靠以填充容器客户端空间，祝您好运找到类似的面板。
但是，如果您使用前缀，TextBox_Custommer、Label_Custommer、Panel_Custommer ......所有与同一上下文相关的控件都会在那个 DropdownList 中搞砸。

我选择了轻松检索嵌套在另一个面板中的面板（在表单预览中只能选择最顶部的面板），所以我坚持使用前缀。

（某些）IDE 的一个很好的补充是在下拉列表旁边过滤组件名称。

---

d) 首字母大写

PINTextBox 还是 PinTextBox ？

如果我能在您的代码中的其他地方理解什么是“PIN”或“Pin”，这两种方法对我来说都是正确的。问题不在于 TextBox 的名称，而在于上下文：我是否清楚地了解了此 TextBox 的用法，还是必须猜测 PIN 或 Pin 是什么？

如果我不得不猜测：

• PINTextBox -> "PIN" 好像是首字母缩写，但我不知道它的意思。 “糟糕的标识符名称”？
• PinTextBox -> 固定什么？

对于“HtmlTag”，它比“HTMLTag”更容易阅读，并且比“HTML_Tag”短。

---

e) 评论：

内联 cmets 在适合 IDE 时非常有用。我讨厌滚动到右边来阅读评论。那你呢 ？但是，我不想问自己评论是否属于上面或下面的代码。你呢？

=> 内联 cmets 既不好也不坏。评论是一个很好的评论，它使用最少的单词添加有用的东西，而不会在工作流程中添加噪音（阅读代码）

---

f) 星号线分隔符：

当您无法按块组织代码时，它们是必须的。今天，你有：

Public Partial Class MyMultipleFilesClass

---

#Region "UserInterface Section"
Private Sub ChangeFormBackground(...)
Private Sub ResizeIconPictureB(...)
' ...
#End Region

---

[+] Private Function OutputLeftWord(...) As String
[+] Private Function FixWordCasing(...) As String
[-] Private Sub ExtractWords(...)
        Dim CurrentWord As String
        While ...
            CurrentWord = FixWordCasing(OutputLeftWord(...))
            ...
        End While
    End Function
[+] Private Sub FormatRTF()

---

你可以创建对象而不是把所有东西都放在Module

等等

---

你问的是主观意见吗？ （在评论中）

我说的是法语。编程语言和 IDE 语言标准是英语。您正在寻求标准化，这是第一个采用。

我不写变量/函数/方法/等。用法语。 （我经常看到德文的变量名。只要我能通过查看代码弄清楚含义就可以了。否则我懒得使用翻译器，继续或有一个一杯茶。）

与收缩与可读性没有真正的关系，但有点相同的问题：“是否清晰？”

如果您担心收缩结束时无法理解，请使用 cmets 或 XML Doc：

''' <summary>
''' Scalar that defines the amount of available power
''' of the Character in this (fight) game.
''' <para>Used to draw Power Level Bar Indicator on top of Screen<para>
''' <para>Used to compute damage bonus upon hit.<para>
''' <para>Used to compute shield strength.<para>
''' </summary>
Private p_CharacterPower As Integer

^^ 每次我忘记它的含义时，我不必右键单击变量，然后“转到定义”来阅读声明旁边的注释。

对于其他方面，我已经在上面解释了我认为这可能是普遍共识：在英语中充满意义的标识符。

但这取决于你。你无法控制别人如何评价你的编码标准，你也不能强迫别人接受你的标准。