Programming "best practice" and XML Comments!!

[Moskus]

I believe this is the most important thing you can do besides keeping the HS3 docs up to date.

Visual Studio has since 2005 supported XML Comments in the code. The HUGE advantage is that when you use that function or sub later on, Visual Studio displays the comments you have entered.

Comments like this:


... gives the programmer this:


I can then just start typing the function name, and up comes a small description of what it does, its inputs when I get to them, and what it returns.
And they very easy to make! In the line above a function/sub, just press ' (the usual comment sign button) three times Visual Studio creates everything you need!



I also see many variables that are prefaced with the type declaration. Microsoft has moved away from that many years ago in .NET due to the fact that .NET can be used by many different programming languages. So while it works great in VB, it looks kind of weird in C# for example.

If you want to (or have to) describe the type in the name, Microsoft suggests putting the Type on the end of the name, so "strSomething" becomes "SomethingString".

"clsPageBuilder", "strTrigger", "strAction" are typical examples. Maybe "cls" and "str" just can be removed? Do they really add information? To me it just looks confusing.




The APIs in HS3 are greatly improved compared to HS2! It would be very sad if it still looks and feels old just because of some old habbits...
The sample plugin could also use some more comments. Have you tried reading the InitIO function? It's confusing at best...

[wetlip]

str means string
b boolean
but what g means in homeseer language i dont know. idem dito cls

[Moskus]

str means string
b boolean
but what g means in homeseer language i dont know. idem dito cls

"cls" is Class, and g is Global (as in a global variable).

... and thanks for proving my point.

[reidfo]

I completely agree with you on this point, Moskus. Since I write in C# it makes things a little messy.

[Rupp]

Where I work we have a set of standards that we go by. All variables are prefixed so we all know what they are without have to go look for there definition.
str = String
g_ = a global variable or member variable
lng = long
int = integer
etc.

Also all controls are prefixed ie
txt for text boxes
lst for list views
lbl for labels
etc

Once you get used to this naming convention it becomes second nature and most employees require this in code review.

Yes the three amigos are a beautiful way of commenting your structures. ''' Three comment characters and fill in the comments.

[Moskus]

Where I work we have a set of standards that we go by. All variables are prefixed so we all know what they are without have to go look for there definition.
str = String
g_ = a global variable or member variable
lng = long
int = integer
etc.

Also all controls are prefixed ie
txt for text boxes
lst for list views
lbl for labels
etc

Once you get used to this naming convention it becomes second nature and most employees require this in code review.

Old habbits are hard to change.
I will make the argument that only because you are used to something, doesn't mean there aren't better ways to do something...

You won't find any declarations like that in MSDN anymore (and seldom anywhere else nowadays), and as I understand it there are simple reasons for that:
- You seldom need them. And if you do, just select the variable, and it will show.
- It makes code messier and harder to understand. It also interrupts readability.

It becomes escpecially bad for the earlier mentioned "strTrigger", "strAction", which aren't strings at all! Maybe they used to be, but they sure as h*ll aren't now.


And why shouldn't also HomeSeer keep to the industry standard?
Read .NET guru Pete Browns quick summary on .NET naming convention here.



The only thing I use "Hungerian Notation" for is controls, like textboxes, lables and list views (an so on), because that actually makes them easier to find. For the rest, you have classes, namespaces and IntelliSense!


EDIT: While we're at it, I'd also put in a vote for longer variable names throughout the SDK and the sample plugin. Using short variable names also disappeared when .NET was introduced. There aren't any practical limits any more, so it's recommended to just write the name fully out. IntelliSense and writing speed takes care of the rest.

[reidfo]

Where I work we have a set of standards that we go by. All variables are prefixed so we all know what they are without have to go look for there definition.
str = String
g_ = a global variable or member variable
lng = long
int = integer
etc.

Also all controls are prefixed ie
txt for text boxes
lst for list views
lbl for labels
etc

Once you get used to this naming convention it becomes second nature and most employees require this in code review.

Yes the three amigos are a beautiful way of commenting your structures. ''' Three comment characters and fill in the comments.

As pointed out earlier though, MS no longer recommends this practice.

[Rupp]

As pointed out earlier though, MS no longer recommends this practice.

Trying to change a large organization isn't easy and the practice does make things work easier. Where are they no longer recommending this?

[Moskus]

I'd also like to comment that I don't mean to be grumpy or to offend anyone. I just want HomeSeer to look as good as it possibly can, and the APIs are important.

You don't want some manufacturer downloading the SDK, shake his head in disbelief, and then skip HomeSeer alltogether.

[reidfo]

Trying to change a large organization isn't easy and the practice does make things work easier. Where are they no longer recommending this?

MS now recommends Camel Case instead, along with all new guidelines. Dropping hungarian notation they say makes code more readable and portable. For instance, hungarian notation that makes sense in VB doesn't always make sense in other languages. It's especially confusing when you look at C++ code where you have data types that don't even exist in other languages.

http://msdn.microsoft.com/en-us/libr...vs.100%29.aspx

[Moskus]

Trying to change a large organization isn't easy and the practice does make things work easier. Where are they no longer recommending this?

"Where" is one thing. "When" was a long time ago, I believe it was formalized some time before .NET Framework 2.0 was released. So ideally HS2 should have been cleaner.

But there's a new chance in HS3!


Changing a huge organization is one thing, but Microsoft have a tendency to know what they are talking about. You will make it easier for your new employees to start working, and you don't teach them an old and awkward notation style. The old timers will have to re-think a little and you can't expect them to be happy the first two-three days, but in the end the results will be easier to read.

I had a friend of mine explained it to me like this:

If you're using a variable and you don't know it's type, then perhaps you shouldn't be using that variable, at least not without investigation.

If you need to preface the variables to find them, you really should re-think your namespaces and classes.

The whole "Main.vb" file is an expample of VB5/6 coding style somewhat updated to .NET. There's a mix of using "s" and "str" for string prefixging, collections are for some reason prefaced with "col" (personally I would prefer "Triggers", "Triggers_Syncronized", "Actions" and "Actions_Syncronized". it IS reasier to read), GoTo really should be avoided at all cost, and the first 10-15 lines seems to be written in VB5.

Here's a quick attempt, but it still could be better (as an example, why aren't stuff like "instance" put in a class for easier accessability instead of a module? Or at least use a namespace so we can figure out what we have to play with and where it's comming from).

        Dim IPaddress As String = "127.0.0.1"

        For Each command As String In My.Application.CommandLineArgs
            Dim parts() As String = command.Split("=")
            Select Case parts(0).ToLower
                Case "server"
                    IPaddress = parts(1)
                Case "instance"
                    Try
                        instance = parts(1)
                    Catch ex As Exception
                        instance = ""
                    End Try
            End Select
        Next

I just read what I wrote and it seems like I'm only negative. I'm really NOT! I just hoped the code was cleaner and easier to understand.

I seriously and heartly believe that cleaning up the code will benefit HomeSeer in the long run. The SDK and sample plugin will look cleaner and more professional. I've always had a feeling that the HS2 documentation and sample plugin was thrown together at the last minute, and HS3 deserves better!