Understanding the contradictions contained in the VB formal agreements guidelines
I was hoping team members could help me sort out the following six conflicting guidelines:
a) Name length:
Advises abbreviation ...
For long [...] terms, use abbreviations to keep the length of the name reasonable.
Consult abbreviation:
DO NOT use abbreviations or abbreviations as part of identifier names.
What is it? To negotiate or not to conclude an agreement? PromotionalNumberTextBox or PromNumTextBox?
b) Event handler names:
Begin event handler names with a noun describing the type of event and then suffix "EventHandler" as in "MouseEventHandler".
Thia doesn't match what Visual Studio automatically generates. See the Button1_Click
event handler below that follows the control format, underscore and event.
Edit: This is actually a contradiction. See jmcilhinney's comment for an explanation.
Private Sub Button1_Click(sender As Object, e As EventArgs) Handles Button1.Click
'...
End Sub
c) Hungarian notation:
DO NOT use Hungarian notation.
... and yet both of them look like a variant of Hungarian notation.
Objects should be named with a consistent prefix that makes it easy to identify the type of object. [...] chkReadOnly [...] lblHelpMessage
Use [...] prefixes to indicate the data type of the variables. [...] intQuantity
d) Abbreviations Capitalization:
For long [...] terms, use [...] abbreviations such as "HTML" instead of "Hypertext Markup Language".
[...] PascalCasing [...] for [...] abbreviations in two letters in length [...] examples: [...] HtmlTag ".
This is ambiguous. Let's say I have an abbreviation PIN. Should it be PINTextBox or PinTextBox?
e) Comments:
Mark comments on a separate line, not at the end of the line of code.
Comments can follow the statement on the same line or span the entire line.
This is ambiguous. Are inline comments recommended or not?
f) Asterisk line separators:
Do not surround comments with formatted asterisk blocks.
Source However, the following example is provided using formatted asterisk blocks:
'*****************************************************
' 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 to share
Here's what I recommend:
Name length
From the point of view of "clean code", variable names should be showing targets . I want the variable target to be clear to whoever is reading my code, so go for a descriptive name rather than using acronyms that the reader may not be aware of.
Event handler names
Since you are using the Visual Basic environment to generate event handler names, I would work with the Visual Basic convention.
However, instead of using the default event handler name that is generated, you should generally recommend general naming rules, add extra information to the method name so the reader knows exactly what it is doing, for example. instead of "Button1_Click" use "SaveButton_Click", for example.
Hungarian notation
Hungarian notation is usually not required as it is easy to inspect the type of a variable by checking it in a modern IDE, for example. ItemCount will be better than intItemCount; adding a shorthand descriptor just adds "noise".
However, the variable name should still show intent, so instead of grdPrices (for example) I would use PriceGrid. The advantage of this approach means that the code can also be understood by everyone, that is, they do not need to know the meaning of the VB prefix abbreviations.
Acronyms Capitalization
Acronyms must be capitalized.
Using this convention, the reader will instantly know that all in caps is an acronym. For example, in your scenario, if you use "PinTextBox" do you mean a text box for a small thin piece of metal used to support, secure or attach things, or a personal identification number (like a PIN)?
Comments
Well-written code should be self-documenting, so comments shouldn't be redundant. However, comments are recommended if you need to document why an esoteric / non-obvious piece of code was used.
When you need to add a comment by placing it on its own line above the code, it works well, as the reader must read the comment first before encountering the code you want to highlight.
Asterisk line separators
If the VB framework automatically generates file headers with asterisks, you can simply deal with it. However, comment blocks without asterisks work better as in practice you will find that sometimes there is so much text there, the comment flows outside the asterisks. It looks much neat if the stars are removed.
source to share
An effective convention would be for someone to understand every word of your code on the fly. Especially your colleagues or depending on the requirements of your employer.
a) Long names.
Are long names easy to read? Not! Find the most obvious meaning using the fewest characters. Or use a different coding approach: Object.Property/ Split your method into multiple
Sub ReturnLeftCup_SwapWithNext_ReturnEveryCups(...)
' ...
' Prefer
Sub ManipulateCups(...)
ReturnLeftCup(...)
SwapCupWithNext(...)
ReturnAllCups(...)
End Sub
b) Suffix EvenHandler.
I understand that this is not inconsistent:
- Enter event handler name / value / action:
ButtonClick
orButton_Click
- Don't write "EventHandler":
ButtonClickEventHandler
orButtonClick_EventHandler
The "EventHandler" line was automatically added to the event handling method in VB6 even though the event name (Click / Enter) was explicitly added.
c) Hungarian notation:
To find every TextBox in your entire solution, it would be easy to search for texts, for example with a search tool or intellisense:
- "TextBox _"
- "TBox _"
- "TBX _"
- ...
If you omit the prefix, I will need to specify the name of any TBox and then search for them one at a time ...
By the way, if you have Label, TextBox and Button associated with the Custommer checkout form.
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 ?
Use prefixes for controls and prefixes for variables / objects (which are not controls)
Prefixes (for example TextB_User
) or suffixes (for example User_TextB
)?
Attention! Personal opinion :
Used prefixes for a long time. Then I changed my mind ... Then I changed my mind again: /
If you use suffixes, form controls are not sorted by type in the IDE's DropdownList. When you forgot you put buttons inside panels, inside tabs, inside a splittercontainer inside ... all docked to fill the client space, and good luck finding the panel is the same.
But if you used prefixes, TextBox_Custommer, Label_Custommer, Panel_Custommer ... all those controls associated with the same context got messed up in this DropdownList.
I chose the ease of extracting a panel nested within another (only the topmost panel can be selected in the form preview), so I stick with the prefixes.
A nice addition to (some) IDEs would be filtering the component name next to the DropdownList.
d) Abbreviations Capitalization
PINTextBox or PinTextBox?
Both might be true for me if I can understand elsewhere in your code what "PIN" or "Pin" is. The problem is not with the name of the TextBox, but with the context: do I have a clear picture of the use of this TextBox or do I need to guess what the PIN or Pin is?
If I have to guess:
- PINTextBox -> "PIN" seems to be an acronym, but I don't know what it means. "Invalid identifier name"?
- PinTextBox -> Write down what?
It is easier to read for "HtmlTag" than "HTMLTag" and shorter than "HTML_Tag".
e) Comments:
Inline comments are good when they fit within the IDE. I don't like scrolling to the right to read a comment. And what about you? However, I don't want to ask myself if the comment belongs to the code above or below. What about you?
=> Inline comments are neither good nor bad. The comment is good when it adds something useful using the least number of words without adding noise to the workflow (reading code).
f) Asterisk line separators:
They were required when you couldn't organize your code in blocks. Today you have:
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()
You can create objects instead of putting everything in Module
and etc.
Have you asked for a subjective opinion? (in comments)
I start a conversation with . The programming language and IDE language standards are English. You were looking for standardization, this is the first thing to accept.
I don't write variables / functions / methods / etc. In French. (I often see variable names in German. That's fine, as long as I can figure out the meaning by looking at the code . Otherwise, I won't use the translator and go on or a cup of tea.)
Has nothing to do with contraction versus readability, but the same problem: "is it clear or not in one frame?"
If you are afraid that the abbreviation ends up incomprehensible, use either comments or 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
^^ I won't have to right click on the variable and then "Define Definition" to read the comment next to the declaration every time I forget its meaning.
For the other bits, I have explained above what I think there might be a general consensus: identifiers full of meaning in English.
But that depends on you. You cannot control how others judge your coding standards, and you cannot force others to conform to your requirements.
source to share