how to write less messy code

1. I tend to avoid commenting what a variable is i.e.
C#: 
public static Device dxDevice1 = null; //Draws on pnl_map
I would tend to give a more descriptive name to the variable

2. No real opinion, I tend to use regions to group related functions / interfaces etc rather than individual methods.

3 + 4. Personally I tend to avoid hungarian naming as a decent compiler / editor will give you the type information and detect and mismatches for you. If you code data type information into a variable that is just another thing that needs to be kept in sync with the code - the number of times I've seen VB code (mainly VB6 but the idea is the same) where variables declared like iOrderNumber weren't integers but longs - they were probably an integer originally but the declaration got updated to a new data type and the variable was never renamed for fear of breaking the code...
If the variables have a meaningful name regardless of length then I'm happy.

I personally would have written the above class definition similar to
C#: 
public class Engine
{
	public static Device MapPanelDevice = null; 
	public static Device SelectedPanelDevice = null; 
	public static Device GraphicsPanelDevice = null; 

	public static Texture tempTexture;

	public static string LayerText = "BOTTOM LAYER"; //Default layer text to be shown
	public static object TextColour = Color.FromArgb(0,255,0);
	public static object TextShadowColour= Color.Black; 
 
	public const int DefaultScreenWidth = 1024; 
	public const int DefaultScreenHeight = 768; 

	//would use a point 
	public Point SelectedTilePosition;

	//rather than two variables
	//public static int iGMapXPos = 0; //Stores the X pos of the current selected tile in the Graphics panel
	//public static int iGMapYPos = 0; //Stores the y pos of the current selected tile in the Graphics panel

	//not sure of the following line so I left it alone
	public static string[,] sArrGraphicsPanel = new string[1000,1000];

	//private Texture spriteTexture;
	//not sure of the following line so left it alone
	public static Texture texDX2;
	public static Texture[] DeleteTile= new Texture[5];
	public static Texture[] RegisterTile = new Texture[5];
I did have to guess at some of the variable usage but you should get the general idea, I would also have tended to wrap the variables inside properties rather than leaving them public but that's another issue entirely.
 
Hi All,


Strangely, I have just been talking to someone in my office about this very topic, and have come up with the following...
Visual Basic: 
'Generic class template...
Public Class genericTemplate

#Region "Class Documentation..."

    'genericTemplate:
    'Author: Paul Weston
    'Initial: 10/10/2005
    '
    'Descritpion:
    '  A generic class template for use with all newly developed classes.
    '  The generic model contains all base regions, definitions, constructors,
    '  destructors and core details relevant to most class definitions.
    '
    '  The objective of this class is to provide a basic standard for all
    '  future classes.
    '
    '  Please modify these comments to suit your own definitions.
    '
    'Members:
    '  None
    '
    'Member Functions:
    '  New()
    '    Basic empty declaration for creator.
    '  Dispose()
    '    Basic empty delcaration for destructor.
    '
    'Version History: (most recent first)
    '  v0.3
    '    Date: 19/01/2006
    '    Author: Paul Weston
    '    Reasons:
    '      Standardisation of region names.
    '      Addition of class documentation region.
    '      Addition of function member regions.
    '      Addition of destructor class.
    '      Addition of remark history region and associated remarks.
    '      Addition of nested class region.
    '  v0.2
    '    Date: <previous>
    '    Author: Paul Weston
    '    Reasons:
    '      Addition of regions.
    '      Local standardisation of region names.
    '      Change in order of regions.
    '  v0.1
    '    Date: <previous>
    '    Author: Paul Weston
    '    Reasons:
    '      Addition of regions.
    ' v0.0
    '    Date: 10/10/2005
    '    Author: Paul Weston
    '    Initial version.

#End Region
#Region "Definitions..."

#Region "Private Members..."

#End Region
#Region "Class Variables..."

#End Region
#Region "Class Constants..."

    'Used by the Dispose member...
    Private isDisposed As Boolean = False

#End Region

#End Region
#Region "Public Members..."

#End Region
#Region "Events..."

#End Region
#Region "Function Members..."

#Region "Constructors..."

    'No params...
    Public Sub New()
        'Do nothing...
    End Sub

#End Region
#Region "Destructors..."

    'Basic destructor...
    Public Sub Dispose()
        If Not isDisposed Then
            isDisposed = True
            'Further code here...
        End If
    End Sub

#End Region
#Region "Other Members..."

#End Region

#End Region
#Region "Private routines..."

#End Region
#Region "Shared routines"

#End Region
#Region "Event Handlers..."

#End Region
#Region "Delegates..."

#End Region
#Region "Nested Classes"

#End Region

End Class

One of our biggest problems is that we don't have any documented standards, everyone writing in their own way. Obviously we do utilise things like standard libraries, but documentation in these libraries is minimal at best.

Using a generic template for class development, similar to the one detailed above, creates a standard for class/code self-documentation.

I have to say that using reasonably defined names for classes, variables etc aids in the documentation process - you only need to obfuscate if the project is going to become public domain. In some cases, of course, it is necessary for variables to be short - it aids speed of access in the variable look-up table, etc. But this is only really applicable to systems that need to have a high execution speed, and even then, I wouldn't be using .NET to do this.


Paul.
 
Last edited:
These coding standards will are a good guide if you can remember all the advice. They are both C# standards, but most of what is said can be applied to VB.Net as well. Note that the language of the stanard is more strong recomendation than written law. That means that unless you have a good reason not to, then you should follow the standard. Following these will make you code less messy and better all around to boot.

http://weblogs.asp.net/lhunt (dowload to the left, *.pdf)
http://www.idesign.net/idesign/DesktopDefault.aspx (download to the right under resorces. Stamped with a big fat "standard", *.pdf)

*A few more I just found
http://www.informit.com/articles/article.asp?p=101147&redir=1&rl=1 (general .Net)
http://www.pbdr.com/vbstd/VBCoding3.htm (covers some VB specific aspects)
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnvs600/html/cfr.asp (a little bigger than just coding style)
 
Last edited:
Just to add that if you are looking at following the MS .Net coding standards then FxCop is a tool you really should be using.
I also agree with mskeel that I would need a very strong argument to use a convention different to the existing framework one, why should I have to remember two sets of naming schemes, parameter passing conventions, error handling mechanisms, event / delegate conventions?
 
Last edited:
Back
Top