General

Query Expression Pattern: article on creating custom Linq sources

Robert Verpalen — Thu, 08 Nov 2007 09:55:00 GMT

Article can be found here: http://blogs.vbcity.com/hotdog/articles/8858.aspx

The new Linq functionality is great and easy to use. Enough tutorials exist on how to use the Linq syntax and on both DLinq and XLinq as well. However when you want to implement your own Linq source, pickings are slim. The ones that are available use the IQueryable interface. However, before that interface and seemingly at the heart of Linq is the 'Query Expression Pattern'
In the following article the basics of that pattern are explored and hopefully provide some insight on how to easily extend on the vastness already provided by Linq: http://blogs.vbcity.com/hotdog/articles/8858.aspx

InstanceDescriptor and the isComplete parameter

Robert Verpalen — Thu, 01 Jun 2006 01:29:00 GMT

This is just a summary of how I overlooked this silly little thing that could have made my designer workings so much easier in the past: how to use the InstanceDescriptor (returned by a TypeConverter) to create a variable inside InitializeComponent and set the properties of that variable, instead of having to set everything inside the constructor. All that was needed, is to set that last parameter (isComplete) to false.

It's so incredible simple and effective, I still can't believe how I could have missed it all that time. Perhaps some of you out there have always been using it and wonder the same thing, but then again perhaps there are others who missed this in the same way and can be spared the same search and use of unneeded CodeDom solutions.

For a long time now, I've been wanting properties to be able to persist in the designer, where the property in this case is an instance. The easy way is to set the designerserializationvisibility to Content, but then you would always need an instance and that doesn't work when using properties with the IExtenderProvider.
In comes the InstanceDescriptor. Creating one is fairly straight forward: by assigning a custom typeconverter to the type used by the property and enabling that typeconverter to return an InstanceDescriptor all properties using that type can be used (how the property is created in the designer is another thing. For example you can have the typeconverter create one automatically when text is typed by implement a convertFrom(string) )
However, I often ended up creating a bunch of constructors to suit the different scenarios without having to include all parameters all the time.
What I really wanted, was the designer to create a variable inside InitializeComponent, and use the default serialization on the properties of that variable. But I never could find any way besides using custom serialization with the CodeDomSerializer.
Then, one day, while trying to getting an InstanceDescriptor to work with a more dynamic construction by using a parameter array of settings in the constructor of my class, I tried setting the isComplete parameter to false. That didn't work for that, (I had to use an array of setting instances as parameter instead of loose setting instances), suddenly a variable appeared inside the InitializeComponent. Not only that, the properties that had to be saved, were indeed present.
Problem was, at that time I changed around several things and feared it was a fluke inside the IDE (yes, yes, me of little faith. I am indeed sorry), until I reviewed the changes and realized the power of that one parameter. By setting that one parameter to false, my class had become so much easier to maintain and could be an effective solution to so much more other past work arounds, that I just had to write this down here. A long story for such a thing and not likely to be read by much people, but at least it will be a reminder to self to keep re-exploring after the re-exploring of the exploring.

.net security policy

Robert Verpalen — Mon, 20 Mar 2006 08:24:00 GMT

We have an intranet at work (yes really :D) And we generally trust its contents. So it would be preferrable if we could just drop a .net application and run it. All righty then: we have to set the local intranet to fulltrust. Didn't work :shock: To make a long version of trial and error short: unless enterprise level security contains fulltrust on either all_code or on the proper zone (intranet, a trusted zone or both), the machinelevel settings will not be used, and vice versa. I still don't know the details on the .net security, but I just wanted something that would trust our intranet, without having to set them manually.

There seem to be plenty of ways to incorporate group enterprise policies in Active Directory and all, but quickly got lost in the documentation. In the end making a class as below seemed like a much quicker way than reading in in the larger security scheme. Again, I'm sure there are much better ways to go about and I don't encourage usage of this code in such, but if you want something to quickly fully trust your intranet, you can use this

This time, the class was created largely in worktime (heh, don't need this at home), but I'm sure the company won't mind me sharing this bit (no company data is included and this way I know I can find it back ;-) . The latter perhaps the main reason for posting :-D )

Code CopyHideScrollFull

using System;
using System.Collections;
using System.Security;
using System.Security.Policy;
using System.Security.Permissions;
using System.Reflection;
using System.Globalization;

/* quick Usage:
*
*
* CompanySecurity.Create("YourCompanyName","StartOfAllowedDomain");
*
*
* eg: CompanySecurity.Create("Subro","\\Subro\");
*
*
* The company name would not strictly be necessary, but this way the settings
* can be easily defined when checking with the 'normal' tools.
* NB: off course when executing the code above, your code will need the proper
* security permissions to execute, so make sure you execute this as a user with
* the needed permissions and from a location from where this is allowed.
*
* For ease of use, you can put this on the intranet and create a batch file
* that temporarily copies the file to the local drive and executes it. Executing
* from the local computer will have the necessary rights. To ensure the proper user
* rights are used, use runas in that batchfile
* (runas /user:\\yourdomain\adminstratoraccount)
*
*/

/// <summary>
/// can create fully trusted company intranet policy
///
public class CompanySecurity
{

public static void Create(string Company,string AllowedDomainName)
{

new CompanySecurity(Company,AllowedDomainName).CreateEntries();

}
public static void Create(string Company)
{

new CompanySecurity(Company).CreateEntries();

}

public readonly string Company;
public readonly string CompanyPermission;
public readonly string CompanyCodeGroup;

FrameworkSecurity.Levels[] levelstoset = new FrameworkSecurity.Levels[]

{ FrameworkSecurity.Levels.Machine, FrameworkSecurity.Levels.Enterprise };

public CompanySecurity(string Company)

:this(Company,null)

{
}
public CompanySecurity(string Company,string DomainName)
{

this.Company = Company;
CompanyPermission = Company + "_permissions";
CompanyCodeGroup = Company + "_zone";
this.DomainName = DomainName;

}

public void DeleteCompanyEntries()
{

foreach (FrameworkSecurity.Levels level in levelstoset)
{

PolicyLevel pl = FrameworkSecurity.GetLevel(level);
if (DeleteCompanyEntries(pl) == 0)

Console.WriteLine("No entries existed for " + Company + " in " + pl.Label + " level");

}

public virtual NamedPermissionSet CreatePermissionset()
{

//create fulltrust
PermissionSet set = new PermissionSet(PermissionState.Unrestricted);

//use
// set = new PermissionSet(null);
//to start an empty permissionset

NamedPermissionSet permissions = new NamedPermissionSet(CompanyPermission, set);
permissions.Description = "Allow " + Company + " local intranet";
return permissions;

}

private string domainName;
string domainCodeGroupName;
public string DomainName
{

get { return domainName; }
set
{

if (value != null)
{

value = value.Trim();
if (value.Length == 0)

value = null;

else if (!value.EndsWith(@"\"))

value += @"\";

}
domainName = value;

if (domainName != null)
{

domainCodeGroupName = Company + "_allow_" + domainName;

}

public bool DomainNameIsSet
{

get { return domainName != null ; }

}

public int DeleteCompanyEntries(PolicyLevel pl)
{

//remove ALL instances of the company groups
int cnt = 0;
for (; ; )
{

bool found = false;
foreach (CodeGroup cg in pl.RootCodeGroup.Children)
{

if (cg.Name.ToLower() == CompanyCodeGroup.ToLower())
{

pl.RootCodeGroup.RemoveChild(cg);
Console.WriteLine("\tCode group " + cg.Name + " removed");
found = true;
cnt++;
break;

}

}
if (!found) break;

}

//adjust existing intranet settings
CodeGroup grI = FrameworkSecurity.GetCodeGroup(pl, FrameworkSecurity.DefaultGroups.LocalIntranet_Zone.ToString());
if (grI != null && grI.PermissionSetName == CompanyPermission)
{

pl.RootCodeGroup.RemoveChild(grI);
grI.PolicyStatement =new PolicyStatement( pl.GetNamedPermissionSet("LocalIntranet"));
pl.RootCodeGroup.AddChild(grI);
Console.WriteLine("\tDefault intranet settings reverted");

}

//remove trusted zone
if (domainName != null)
{

//add as trusted zone
CodeGroup grTrusted = FrameworkSecurity.GetCodeGroup(pl, FrameworkSecurity.DefaultGroups.Trusted_Zone.ToString());
if (grTrusted != null)
{

if (grTrusted.PermissionSetName == CompanyPermission)
{

grTrusted.PolicyStatement = new PolicyStatement(

new NamedPermissionSet("Internet"));

Console.WriteLine("\tPermissionset on trusted zone reverted to internet settings");

}
for(;;)
{

CodeGroup grD = FrameworkSecurity.GetCodeGroup(grTrusted, domainCodeGroupName);
if (grD == null) break;

grTrusted.RemoveChild(grD);

pl.RootCodeGroup.RemoveChild(grTrusted);
pl.RootCodeGroup.AddChild(grTrusted);
cnt++;
Console.WriteLine("\tTrusted zone removed");

}

//remove permissions
NamedPermissionSet ns = pl.GetNamedPermissionSet(CompanyPermission);
if (ns != null)
{

pl.RemoveNamedPermissionSet(ns);
Console.WriteLine("\tNamed permission set removed on " + pl.Label + " level");
cnt++;

}

SecurityManager.SavePolicyLevel(pl);
return cnt;

}

public void CreateEntries()
{

Console.WriteLine("Setting permissions for " + Company);
foreach (FrameworkSecurity.Levels level in levelstoset)
{

PolicyLevel pl = FrameworkSecurity.GetLevel(level);
CreateEntries(pl);

}

public void CreateEntries(PolicyLevel pl)
{

if (pl.RootCodeGroup.Children.Count == 0 &&

pl.RootCodeGroup.PermissionSetName == "FullTrust")

{

Console.WriteLine(pl.Label + " not changed, all code allready has fulltrust");
return;

}

DeleteCompanyEntries(pl);

//create a full trust permission
NamedPermissionSet permissions = CreatePermissionset();
PolicyStatement polstat = new PolicyStatement(permissions);

//create a new codegroup
UnionCodeGroup gr = new UnionCodeGroup(

new ZoneMembershipCondition(SecurityZone.Intranet),
polstat);

gr.Description = "Allow applications in the " + Company + " intranet";
gr.Name = CompanyCodeGroup;
Console.WriteLine("\t" + CompanyCodeGroup + " added");

if (domainName != null)
{

//add as trusted zone
CodeGroup grTrusted = FrameworkSecurity.GetCodeGroup(pl, FrameworkSecurity.DefaultGroups.Trusted_Zone.ToString());
if (grTrusted != null)
{

pl.RootCodeGroup.RemoveChild(grTrusted);

}
else
{

grTrusted = new UnionCodeGroup(

new ZoneMembershipCondition(SecurityZone.Trusted),
new PolicyStatement(new NamedPermissionSet("Internet")));

grTrusted.Name = FrameworkSecurity.DefaultGroups.Trusted_Zone.ToString();

}

UrlMembershipCondition ums = new UrlMembershipCondition(domainName + "*");
UnionCodeGroup grD = new UnionCodeGroup(ums, polstat);
grD.Name = domainCodeGroupName;
grD.Description = "Allow all applications in the domain " + domainName;
grD.PolicyStatement = new PolicyStatement(new NamedPermissionSet("FullTrust"));
grTrusted.AddChild(grD);
Console.WriteLine("\t"+ CompanyPermission + " (permissionset) added");

pl.RootCodeGroup.AddChild(grTrusted);

Console.WriteLine("\tTrusted zone added");

}

//NB use addchild and NOT Children.Add
pl.RootCodeGroup.AddChild(gr); // .Children.Add(ZoneGroup);

//add the group
FrameworkSecurity.SetNamedPermissionSet(pl, permissions);

//save the changes
SecurityManager.SavePolicyLevel(pl);

Console.WriteLine("Policy written to " + pl.Label + " level");

}

}

/// <summary>
/// Functions around the security settings. Not all are needed perhaps, but like
/// this I know where to find them ;-)
///
public static class FrameworkSecurity
{

#region enums
public enum Levels
{

Enterprise, Machine, User

}
public enum DefaultGroups
{

My_Computer_Zone,
LocalIntranet_Zone,
Internet_Zone,
Trusted_Zone,
Restricted_Zone

}
public enum DefaultPermissions
{

FullTrust,
SkipVerification,
Execution,
Nothing,
LocalIntranet,
Internet,
Everything

}
#endregion

#region Levels

public static PolicyLevel GetLevel(Levels level)
{

IEnumerator policyEnumerator = SecurityManager.PolicyHierarchy();
// Move through the policy levels to the Machine policy level.
while (policyEnumerator.MoveNext())
{

PolicyLevel currentLevel = (PolicyLevel)policyEnumerator.Current;
if (currentLevel.Label == level.ToString())
{

return currentLevel;

}

}
return null;

}
#endregion

#region PermissionSets

public static NamedPermissionSet GetPermissionSet(Levels level, string Name)
{

return GetPermissionSet(level, Name, false);

}
public static NamedPermissionSet GetPermissionSet(Levels level, string Name, bool Create)
{

return GetPermissionSet(GetLevel(level), Name, Create);

}
public static NamedPermissionSet GetPermissionSet(PolicyLevel pl, string Name)
{

return GetPermissionSet(pl, Name, false);

}
public static NamedPermissionSet GetPermissionSet(PolicyLevel pl, string Name, bool Create)
{

foreach (NamedPermissionSet ps in pl.NamedPermissionSets)
{

if (ps.Name == Name) return ps;

}

if (Create)

return new NamedPermissionSet(Name);

return null;

}
public static NamedPermissionSet GetPermissionSet(PolicyLevel pl,DefaultPermissions p)
{

return GetPermissionSet(pl, p.ToString());

}
public static NamedPermissionSet GetPermissionSet(Levels level, DefaultPermissions p)
{

return GetPermissionSet(level, p.ToString());

}

public static void SetNamedPermissionSet(PolicyLevel pl,NamedPermissionSet ns)
{

if(pl.GetNamedPermissionSet(ns.Name) != null)

pl.ChangeNamedPermissionSet(ns.Name,ns);

else

pl.AddNamedPermissionSet(ns);

}
#endregion

#region Code groups

public static CodeGroup GetCodeGroup(Levels level)
{

return GetLevel(level).RootCodeGroup;

}
public static CodeGroup GetCodeGroup(Levels level, string Name)
{

return GetCodeGroup(GetLevel(level), Name);

}
public static CodeGroup GetCodeGroup(Levels level, string Name, bool Recursive)
{

return GetCodeGroup(GetLevel(level), Name, Recursive);

}
public static CodeGroup GetCodeGroup(PolicyLevel pl, string Name)
{

return GetCodeGroup(pl.RootCodeGroup, Name);

}
public static CodeGroup GetCodeGroup(PolicyLevel pl, string Name, bool Recursive)
{

return GetCodeGroup(pl.RootCodeGroup, Name, Recursive);

}
public static CodeGroup GetCodeGroup(CodeGroup InGroup, string Name)
{

return GetCodeGroup(InGroup, Name, true);

}
public static CodeGroup GetCodeGroup(CodeGroup InGroup, string Name, bool Recursive)
{

if (Name == null) return InGroup;
CodeGroup res = null;
foreach (CodeGroup gr in InGroup.Children)
{

if (gr.Name == Name)
{

res = gr;
break;

}
if (Recursive)
{

res = GetCodeGroup(gr, Name, Recursive);
if (res != null) break;

}

}
return res;

}

#endregion

}

Whidbey: retrieving all SQL server instances

Robert Verpalen — Mon, 06 Jun 2005 03:55:00 GMT

One of the things that was always an issue (at least for me ;-) ) was to get a list of all sql servers available to the machine the code was run at.

Sure, there was the sqldmo,netserverenum and even a method using odbc, but each needed api calls (or interop). But for those of you interested: great news: whidbey has the requiring of the information build in !!!! :-)
The SqlDataSourceEnumerator gives back a datatable with information on the available servers. (See the link to find out precisely what information)

From .net 2.0 and up, filling a listbox with the server-names can be as simple as:
listBox1.DisplayMember = "ServerName";
listBox1.DataSource = System.Data.Sql.SqlDataSourceEnumerator.Instance.GetDataSources();

Hotdog's guide to maintainable code

Robert Verpalen — Wed, 11 May 2005 08:55:00 GMT

This guide holds a couple of points to what my personal view is regarding what sort of code is well maintainable. They are only my opinion and therefore by no means actual rules. Some subjects may seem quite obvious, but nonetheless these points are often not used.
The points are used as general as possible to programming languages in general. Most things are the same in procedural as well as object oriented environment. Sometimes reference are made to language specific elements in eg vba, vb6, vb.net or C#, but mostly it's just general programming.
The most simple rule: most copy and paste is bad! Cut and paste to a new function or method is much better.

The guide is a work in progress one, adding things as they come along. At this stage it's a looooong way from finished. For pseudo code a vb'ish approach is chosen, because this can be read by most programmers.

Index:
Constants
Structures
Loops
Split code
Use objects
Structures
Wrappers
Documentation

constantly use constants (or variables)

It doesn't have to be a constant, it can also be a variable, but reuse that value! If you have to use a value twice, put it in a constant if possible, otherwise a variable. It's that simple. It may be more work to set up, but it can save you a whole lot of headaches! The same with calculations, don't copy and paste them! If you need them twice, put the result in a variable or function.

A simple example: a tax percentage in calculations. Now here's something that's used a lot and might never change, but what if it does? In the Netherlands the percentage is 19% (for normal products and rates, food products and some other exemptions use a different percentage) It's very easy to simply use 1.19 each time to calculate the price including taxes. A previous employer used to do that and of course everything worked fine. Now the luck was, so far that value itself hasn't changed. The consequences would be enormous. It is used in global code, in forms, in reports and a simple search and replace of 19 would not be possible. What would be safer is to define a constant (double 0.19) and reuse that. For getting the price including taxes, you could use a function. That way: change the constant, and everything works ok. Reusing a value hard coded will give non compile errors which means a lot of harm can be done before the user ever finds out that he has calculated profits wrong for an extended period. And you know who'll get the blame.. (and rightly so in this case :-/ )
Having the calculation and value in one place is not only the best for if the value itself changes. Once I got the request of having the taxes variable per clienth, since the customer also had Belgian and German customers himself, for whom the percentage was different. He didn't expect this to be a big adaptation, but it certainly was! It would have been an adaptation anyhow, but there was no way I could guarantee that everything was calculated in the right manner, because all over the place the 19 was hard coded. This particular piece of software was written in Access (hey not my choice ;-) ) which made it harder: it could be used in reports, in calculated fields in a form and in macro's. Luckily the latter weren't used, but in forms and reports, that value could not be found unless going through all the seperate forms in designmode: no search and replace possible in those. As a sidenote, I ended up writing a tool that searched through all fields in all forms and in all reports, but all that could have been avoided simply by using function. It did have to be a function in this case, because the customer country is important as well, so the function needed at least 2 parameters. Changing the function would cause compilation to show all the points that need to be altered. Access is a bad example in this case because the calculated fields in forms and reports are never compiled. That's why I think Access is great for (and intended for) quick projects, but not for resale projects
The above is an example with a very rigid value, but I've seen primary keys used in this way -shock- . Yep, using a pkey hard coded is dangerous in itself, but it was used multiple times in the code and I don't mean with a variable.... You can imagine the fun that could create when dealing with a development backend versus a production backend... Besides: the readability is often much easier when using named variables.
Don't even get me started on repeated calculations :-p Ever seen this: If (somecalculation) > 0 then functionA(somecalculation) else functionB(somecalculation) A setup like this means that the calculation is always done twice (once for the comparisson and once for one of the blocks). Not only does this give an overhead, but it also means that if you want to alter the calculation, you need to do it three times. If the blocks are this small, you will notice that the calculation is redone, but with a couple of lines between them, you may miss that second calculation. All that could be prevented by simply assigning the result to a temporary variable. Not that much effort and much safer.

wrong:

function PrepareProductA_Order(Q as integer)
      if Q mod 4 <> 0 then
             display message: "the quantity has to be a multitude of 4"
      else
               if CheckNumberOfBoxes(Q/4)
                    CreateLabel(Q/4,4)
                    SubtractBoxes(Q/4)
end of function

In the example CreateLabel is a function that creates a barcode label and needs the number of boxes and the number of products per box. SubtractBoxes edits the value of boxes in stock. A logical next step would be to subtract the ProductA quantity or whatever, but more things miss from the code. No result is being returned for example, but that's outside the focus of what the example is meant for ;-) Better would be:

Constant ProductAperBox = 4

function PrepareProductA_Order(Q as integer)
    if Q mod ProductAperBox <> 0 then
       display message: "the quantity has to be a multitude of " & ProductAperBox
    else
       boxes as integer = Q/ProductAperBox
       if CheckNumberOfBoxes(boxes)
          CreateLabel(boxes,ProductAperBox )
          SubtractBoxes(boxes)
end of function

Lots of variations might be possible on the code, but the general line is: don't hard code values unless necessary (retrieving the value out of an user editable backend might be better) and if you do hard code them: do it once.

Another example: this I saw not only at my previous work, but is a very commonly seen scenario. Of course it isn't wrong, but if you add or remove a control in this scenario, you have to do it at 2 places. Sounds easy enough, but it's also easily forgotten.
This example only has 4 fictional controls, but actual code exists with a page filling blocks.
wrong:

if SomeCriteriumStatementHere
      Control1.Enabled = true
      Control2.Enabled = true
      Control3.Enabled = true
      Control4.Enabled = true
else
      Control1.Enabled = false
      Control2.Enabled = false
      Control3.Enabled = false
      Control4.Enabled = false

Better:

booleanVariable b = SomeCriteriumStatementHere
      Control1.Enabled = b
      Control2.Enabled = b
      Control3.Enabled = b
      Control4.Enabled = b

Better still: use loops The example above still depends on a repitition of code which could also be 'dangerous'. See the loops section if you want to know why ;-)

Back to index

Structurize with structures

One much occuring scenario is that an address (like in the real world you know, not like one of those pointer thingies) is used. For that address a couple of variables of different types are used. But those variables are rarely needed individually, mostly the entire address is used. Then can't we pass the address as a whole, as a single element. Of course we can :)

For an example why don't we take something not so everyday as an address of person data. With those by now we know what to expect and use structures right away (don't you ;-) )
Let's take a simple scenario where a program keeps score. Important for procedures in this point in time is just the Name and score.

-- under construction --

IIn the beginning days the only choice we had of keeping data indexed, was with a 'multi-dimensional' array. As long as you're working on that bit of code your head knows exactly what arr(0,1,3) points to. You may even have it documented (you should anyway ;-) ), but having to change something a couple of months later on is a headache generating business.
And what for? If we make a structure (as it's called in .net, the vb6 and vba equivalent is a Type) or even a class, that array can contain a much, much clearer picture of what it contains. Granted, if you want to Loop a lot, the multidimensional array can be more convenient, but languages such as the .net ones, can implement that behaviour with reflection.

Can't remember of languages of Turbo Pascal had something as types, but they have been around for quite some time now. Still they were one of the unknowns to a lot of vb6 programmers. The main reason of this was probably that many available examples still used multi-dimensional arrays. Don't get me wrong, sometimes multi-dimensional arrays are still needed. It will depend on the situation whether a structure is used or a multidimensional array, but often the latter is used unnecessarily.

--Example coming later ---

Back to index

Use loops

Loops are one of the first thing that were introduced into programming, because that simply was the only way that you could ensure for example going through an entire collection of unknown length. At the most basic level, this simply means that the 'next' returns to the memory address the first line of the 'for' began, until a criterium is met which jumps to the address after the 'next'.

Loops are mostly used for going through collections, but why limit yourself to existing collections? In the constants section, the following example was used:

booleanVariable b = SomeCriteriumStatementHere
      Control1.Enabled = b
      Control2.Enabled = b
      Control3.Enabled = b
      Control4.Enabled = b

Nothing wrong with that code on itself, but what a shame of putting .enabled every time... This on itself may be quickly enough done, but now you decide, it has to be enabled, but readonly. Search and replace, yeah sure, why not. Now you decide you want to make it readonly and set a tooltip. You get the picture.

Array controls = {Control1,Control2,Control3,Control4}
booleanVariable b = SomeCriteriumStatementHere
foreach LoopControlVariable in controls
LoopControlVariable.Enabled = b

Adding controls is simply adding to the array. Changing the behaviour for all is simply changing inside the loop. The array creation itself depends on the language being used, but there's always an easy way to create one(although in vb6/vba I generally had to create inbetween functions using a paramarray :-/ ) The controls in the example are called neatly called ControlX, making another loop possible, but actual controls won't be that neatly numbered of course. If you use the same collection multiple times, that of course can be put in its own functions or declared at the form initialization.

Back to index

Split up code

Long blocks of code are often the hardest to debug. It is unclear, what portion does what. Even when commented start of this and end of that, what the debugger is looking at, is a long list of text. Splitting that block of code into several sub-methods is easier to look at and helps with the reusability.

This section will be a somewhat abstract one, since there are no clear outlines as to when code should be split up. Then again, if you have seen methods that fill a couple of pages, you'll hopefully agree with the need of splitting up code.

In the 'old' days, blocks of code were all that was possible. Methods did not exist. The code lines were numbered and you could goto/gosub such a line, but no matter how much I liked the old C64, that's not something I'd choose for now ;-)
Even with the procedural programming that was introduced next, you'll still have some scenarios that will call for long blocks of code because of all the variables used, but in the OOP world, that's no excuse either.

For more on the latter, there's the 'Use objects' section, but to start with the more general approach, imagine a form constructor (or load event), which initializes that form. It sets up a new dataconnection, it determines which controls should be disabled for the current user and builds up a (context)menu specific for that same user.

You could say they sound like specific steps, and so they also can be easily implemented: a method for each step. This may sound like overkill at first, but keeping those steps separated will also prevent variables interfering with each other. Though the downside could be that more variables may have to be declared, because they can no longer be reused, this also helps with adapting the code at a later point. -- if there is an amount of variables reused in the methods, implementing an object instead should be considered --

If the 1st advantage is readability (and thus maintainability), the 2nd advantage would be the reusability. If the current-user changes or his/her rights change, steps 2 and 3 would have to be done a 2nd time. Keeping that in mind, the structure of 3 methods for the 3 steps, is not entirely what we want.

As you might have commented in yourself already, having steps 2 and 3 completely separated, would call for determining the current user twice and the way the current user is determined may change some time as well. The first step there of course would be to use a function.
The 2nd is to have one method that calls the methods for steps 2 and 3. This method can be seen as the method that sets the user options. All in all, instead of one potentially large block, the layout would look more like:

Method SetDataConnection

UserObject function GetCurrentUser() (this can be a global function )

Method SetUser
       UserObject UserVariable = GetCurrentUser()
       SetControls(UserVariable)
       CreateMenu(UserVariable)
End Method
(for those languages that support overloading, an extra option would be to insert an extra method:
     Method SetUser(UserObject))

Method SetControls(UserObject)

Method CreateMenu(UserObject)

I realize all too well, that this would be too much overkill if the steps themselves are just a couple of lines of code. Unless I need to reuse them, I would keep those lines together in the load event as well. But still neatly in their own little blocks, so if they needed to be split after all, methods could be created quickly.
All in all, it depends on how large the block is becoming and not always will we be able to have anticipated the code-growth, but it's something to keep in the back of our heads, just in case we will need to split that code up later. And of course, if it's known from the beginning that the code will become a large block, split it up right away.
Finally the example above would cause double coding if the menu creating and control enabling were entangled in the same loop or used a lot of the same variables. Be sure to think of creating an object in that case!

Back to index

Use objects

As described in the Structures section, keeping multiple related values inside a structure (= also an object) keeps them nicely together and easier to pass around. But now we want to be able to do all sorts of things with those values, we need to check if an address is valid or if a user has specific rights. Or maybe we just have to do a lot of calculations and keep a subresult.

Now what is often seen, is that a bunch of methods are added, that take the structure as a parameter or worse yet if no structures are used, a lot of loose variables. But the whole intention of OOP is that a method can be called from within that object itself.

Although the difference in a lot of modern OOP languages no longer exists in this manner, for this guide we'll see structures as objects that just contain values (think of vb6 types) and objects as elements that can also contain methods/functions and properties. In this viewing point, all structures are objects, but an object doesn't have to be a structure.

For the sake of mentioning it: in modern languages as .net, structures can have methods and functions as well. The difference is in how they are stored, but that's outside the scope of this guide. There are several articles on structures versus objects on the internet if you look for them.

Objects and OOP is not just something invented for the fancy words. They really can make your programming life a lot easier. Further than that, they make some programming that seemed almost impossible, much easier. We just mustn't forget to use those options.

Back to index

Keep things strongly typed

Back to index

Wrap things up

Back to index

Document your code

Yeah, yeah, I know, is probably your first reaction. At least it would be if I read this :D Still, this very point is the most easily neglected. Especially when in the middle of developing, the start goes well, documenting the important functions. Then you delete that function and all documentation was for nothing. That's the main reason I skip documentation, until there's a form of final draft. Only.... then you're busy with something else.

I wouldn't be able to tell you at which stage you should document. There may be alot of opinions on that subject, but the truth is: "it always depends". Many times documentation you will call a function and find it undocumented. Although late, this might be a good time to do a quick documentation (assuming it is your function). Since you're calling it, you'll probably know at that time what it does. The details will come back to you when going through it. But 2 months later, you'll have to dive much deeper to recollect the same. Let alone when working with multiple people on the same project. Especially .net has great methods to document functions and classes (with the summarize tags), making even creating an msdn style help interface a breeze, but you will still need to document.
The bottom line: if you skip such a basic part as doing a basic documentation, you may have a lot more work laid out for you later on.
NB: I'm absolutely not talking about those anoyingly long 'rules' that some companies implement on each and every function described with every function described. Commentary should be useful, not obligatory.

eg. some pseudecode (green is commentary, it's only pseudocode, so I didn't include any tags or commentary characters):

This is useless

----------------------------------------------------------------------
function: GetCurrentUserName
----------------------------------------------------------------------

description: returns name of current user

returns: name of current user

returntype: string

parameters: none

----------------------------------------------------------------------
string-function GetCurrentUserName
return CurrentUser.Name
end of function

Some companies expect comment blocks like this, so the programmer makes them, but adds nothing. The only effect the commentary has, is a Homer Simpson 'duh' reaction. Now imho it only makes finding code harder. I've seen the example above where the comment block is much larger then the function itself with non helpful commentary. Even where the function was only one line and the name of the function said everything that it did, it had about 6 lines of commentary formed as in the example above.
If you have a piece of code with a lot of these functions underneath eachother, this can be very annoying. Of course this is just an opinion. If you include commentary, make sure it says something (and otherwise keep it short ;-) ), eg:

returns the name of the user as it was validated in the current thread.
For more info see reference to CurrentUser property
---------------------------------------------------------------------
string-function GetCurrentUserName
return CurrentUser.Name
end of function

The line (------) is optional and will depend on the IDE being used. In some IDE's the separation between functions wil be clear enough. In the .net designer, the summery and other xml tags make lines as this unnecessary.

Back to index

Website for my wife

Robert Verpalen — Sat, 23 Apr 2005 02:41:00 GMT

The website: www.colourfulnails.tk

My wife sets arificial nails and one of the rooms in our house has been turned into a salon. Of course that also meant that she needed a website. To be truthful, I never actually made a website before, and my first endeavours with JavaScript and HTML in general were with the RTF to HTML converter (BTW, I noticed PrettyCode.print has conversion to HTML build into it, so anyone interested in that kind of conversion is probably a lot better off by using PrettyCode)
So this was a nice oppertunity to try out some 'webbing' and once again I have to say I like the build up of web objects and how they interact with JavaScript (although debugging is a pain in the ... uhm... nose for example. Since the whole thing was done from ground up, that is, no use of existing scripts, there was a lot of debugging involved :-( )

Anyway, the result is in the link above and my wife asked me to share it on this blog (the more hits the merrier I suppose ;-) ), although for non Dutch speakers that website will mean little and the style may not appeal to the male viewers, perhaps the lady population has some comments how some changes might attract them more to get artificial nails. :-) (First thing would be pictures, but there are no pictures on the site yet, we need to get or borrow a digital cam first :-/ )