I was hoping fellow members could assist me in making sense of the following six contradictory guidelines:
Advises abbreviation...
For long [...] terms, use abbreviations to keep name lengths reasonable.
Advises against abbreviation:
DO NOT use abbreviations or contractions as part of identifier names.
Which is it? To contract or not to contract? PromotionalNumberTextBox or PromNumTextBox?
Begin event handler names with a noun describing the type of event followed by the "EventHandler" suffix, as in "MouseEventHandler".
Thia doesn't correspond with what Visual Studio automatically generates. See Button1_Click event handler below that follows the format of control, underscore and event.
Edit: Not, in fact, a contradiction. See comment by jmcilhinney for explanation.
Private Sub Button1_Click(sender As Object, e As EventArgs) Handles Button1.Click
'...
End Sub
DO NOT use Hungarian notation.
...and yet both of the following seem 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 a variable's data type. [...] intQuantity
For long [...] terms, use abbreviations [...] for example, "HTML", instead of "Hypertext Markup Language".
[...] PascalCasing [...] for [...] acronyms over two letters in length [...] examples: [...] HtmlTag".
This is ambiguous. Let's say I have the acronym PIN. Should it be PINTextBox or PinTextBox?
Put comments on a separate line instead of at the end of a line of code.
Comments can follow a statement on the same line, or occupy an entire line.
This is ambiguous. Are inline comments recommended or not?
Do not surround comments with formatted blocks of asterisks.
Source However, the following example using formatted blocks asterisks is also provided:
'*****************************************************
' 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.
'*****************************************************
Here's what I advise:
From a "clean code" perspective, variable names should be intention revealing. I want a variable's purpose to be clear to whoever reads my code, so go for a descriptive name as opposed to using abbreviations which the reader might be unaware of.
As you're using the Visual Basic framework for generating event handler names, I'd work with Visual Basic's convention.
However, instead of opting to use the default event handler name that gets generated you should, as the general naming conventions recommend, add more information to the method name so the reader knows exactly what it does e.g. instead of "Button1_Click" use "SaveButton_Click" for example.
Hungarian notation is generally not required as it is easy to view the variable type by inspecting it in a modern IDE e.g. ItemCount would be better that intItemCount; adding an abbreviated descriptor just adds "noise".
However, a variable name should still be intention revealing, so instead of grdPrices (for example) I'd use PricesGrid. The benefit of this approach means that the code can also be understood by all i.e. they won't need to know the meaning of the VB prefix abbreviations.
Acronyms should be capitalised.
Using this convention a reader will instantly know that a word all in caps is an acronym. For example in your scenario if you use "PinTextBox", do you mean a text box for a small slender piece of metal used to support, fasten or attach things, or a Personal Identification Number (i.e. PIN)?
Well written code should be self-documenting, so comments should be unnecessary. However comments are recommended if you need to document why an esoteric/non-obvious piece of code has been used.
When you have to add a comment, placing it on its own line above the code works well, as a reader has to read the comment first before they encounter the code you want to highlight.
If the VB framework automatically generates file headers with asterisks, then you could just work with that. However comment blocks without asterisks work better as in practice you find that sometimes there's so much text, the comment flows outside the asterisks. It looks far neater if the asterisks are removed.