vb.net - 了解在 VB 的官方约定指南中发现的矛盾

Question

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

a) 名称长度:

建议缩写...

For long [...] terms, use abbreviations to keep name lengths reasonable.

Source

反对缩写的建议:

DO NOT use abbreviations or contractions as part of identifier names.

Source

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

b) 事件处理程序名称:

Begin event handler names with a noun describing the type of event followed by the "EventHandler" suffix, as in "MouseEventHandler".

Source

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

编辑:事实上，这并不矛盾。请参阅 jmcilhinney 的评论以获取解释。

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

c) 匈牙利表示法:

DO NOT use Hungarian notation.

Source

...但以下两个看起来像是匈牙利表示法的变体。

Objects should be named with a consistent prefix that makes it easy to identify the type of object. [...] chkReadOnly [...] lblHelpMessage

Source

Use [...] prefixes to indicate a variable's data type. [...] intQuantity

Source

d) 首字母缩略词大写:

For long [...] terms, use abbreviations [...] for example, "HTML", instead of "Hypertext Markup Language".

Source

[...] PascalCasing [...] for [...] acronyms over two letters in length [...] examples: [...] HtmlTag".

Source

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

e) 评论:

Put comments on a separate line instead of at the end of a line of code.

Source

Comments can follow a statement on the same line, or occupy an entire line.

Source

这是模棱两可的。是否推荐内联评论？

f) 星号行分隔符:

Do not surround comments with formatted blocks of asterisks.

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

'*****************************************************
' 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 的约定。

但是，与其选择使用生成的默认事件处理程序名称，不如按照一般命名约定的建议，向方法名称添加更多信息，以便读者准确了解它的作用，例如例如，不要使用“Button1_Click”，而是使用“SaveButton_Click”。

匈牙利表示法

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

但是，变量名称仍然应该是意图揭示的，所以我将使用 PricesGrid 而不是 grdPrices(例如)。这种方法的好处是代码也可以被所有人理解，即他们不需要知道 VB 前缀缩写的含义。

首字母缩略词大写

首字母缩略词应大写。

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

评论

写得好的代码应该是自文档化的，所以注释应该是不必要的。 但是如果您需要记录为什么使用了一段深奥/不明显的代码，建议使用注释。

当您必须添加评论时，将其单独放在代码上方的行中效果很好，因为读者在遇到您要突出显示的代码之前必须先阅读评论。

星号行分隔符

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