Mike’s Dump

June 25, 2007

RE: Is there an issue with this or am I not getting enough oxygen?

Filed under: Code — mikesdump @ 2:01 pm

In my previous post I showed an example of what not to do when writing comments. To my amazement this non-rant generated almost as many comments as this post.

After reading the comments and giving it some more thought I wanted to post a follow-up. I don’t believe these type comments are unique to a tool like VBCommenter, one development shop or one programming language. I believe this is a very common issue when documenting source code.

I had another post a couple years ago about documentation and my views haven’t really changed. I still believe the most important piece of documentation for a project is the requirements.

If you insist in commenting the code (which I’m not arguing against) I suggest the following rules:

Document WHY not WHAT
Even really crappy code can be debugged. Call me sick but I kind of like debugging crappy code from time-to-time because it is extra satisfying when I fix it. When you are cursing the previous developer’s name are you screaming at them, “WHAT are you doing”? or “WHY did you do that”? I find it a lot easier to figure out the what but the why can be a little trickier.

Remember you who are writing for

The primary person the in code documentation is for is the developer(s) that inherit your code not for you. I believe a class header outlining the purpose of the class is far more valuable than commenting every method. If you had to explain the application to a developer that was going to take over for you what would you tell them? Would you say, “here is the page_load event, it will load the page”? Probably not, you are hopefully going to tell them some of the challenges you ran into and why the application is the way it is.

Never Copy and Paste Comment Block headers

Please, if you must copy comment headers remember to update them. I don’t know how many times over the years I have read the comments of method A right above method B because the developer copied the comments and didn’t update them.

Read them and keep them current

If you are maintaining some code and the person before you took the time to write good comments make sure they are still current after your change. If you aren’t going to bother updating them it is better to delete them than leave comments that don’t match the code.

Commenting code can add value to a project but it is a team effort. I don’t believe there is any magic to writing good comments but it does take time and you do have to put some thought into it. If you hate writing comments that much you could always try this.

Advertisements

June 20, 2007

Is there an issue with this or am I not getting enough oxygen?

Filed under: Code — mikesdump @ 1:43 pm
''' -----------------------------------------------------------------------------
''' <summary>
'''     Called on load of the page
''' </summary>
''' <param name="sender"></param>
''' <param name="e"></param>
''' <remarks>
''' </remarks>
''' <history>
''' 	Somebody	8/17/2005	Created
''' </history>
''' -----------------------------------------------------------------------------
Private Sub Page_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load
Bla
Bla
Bla
End Sub

Ok. Instead of me going on a rant on why I think the above comment block is a complete waste of time and how it takes away from code readability instead of enhancing I’m hoping somebody, anybody can say something useful about a comment block like this.

(Some might argue that it tells you when the method was created but assume the development shop that produced this uses source control.)

July 29, 2006

Code Metrics and the Decor Consultant

Filed under: Code,Home — mikesdump @ 5:15 am

We have been discussing incorporating a few different code metrics in our build process at work. I am personally interested in three different values: The number of lines of code in the project, number of unit tests written (using NUnit), and percentage of code covered by unit tests using NCover.

Unit testing is new to several developers at our shop and tracking these numbers main purpose is to keep the conversation on unit testing going. Reviewing these stats regularly provides an opportunity to talk about challenges found during unit testing or maybe newly tried techniques that make unit testing easier. The key to these stats is they are in no way tied to a developer’s compensation.

Why not tie metrics to compensation?

If you were told that you would be paid one dollar for every unit test you wrote and there was no criteria on what the test needed to do how many tests would you write? I know I would game the system. I would write my unit test generator, generate five million unit tests, collect my check and retire by noon.

The D�cor Consultant

We have been looking high and low for a bedroom set and finally found something we liked at Sears. The set we liked was a little pricey but our “D�cor Consultant” said she would be able to adjust our bill a week later because this particular set was going on sale. Also it happened to be scratch and save day when she would adjust the price so she would throw that discount in there too. I thought that was nice.

Delivery Day

Our bedroom set was supposed to show up sometime between 8 am and 5 pm (don’t you love how specific that is). We get a phone call first thing in the morning that everything is in the shipment except the footboard. The person on the phone was very friendly and apologetic so I thought crap happens and brushed it off.

When the delivery guy shows up he asks if we received a call about the footboard not being with the shipment and apologized again for the inconvenience. When he was taking the dresser out of the packaging he checked it over and noticed it was damaged. He brought it to our attention right away and said we could ask for a discount or get a new one ordered. Sandy and I both wanted a new one. He said in the mean time we could use this one if we would like. We thought that would be nice because we didn’t know how long it would take to get the new one and I was getting tired of living out of boxes.

Back to the “D�cor Consultant”

Sandy calls up the sales person and explains the situation. She tells Sandy to phone and track down where our footboard is. When discussing the broken dresser she argues with Sandy because they want to try to get someone out in the next week or so to try to repair the broken dresser (we refused). Finally she agreed to order us a new dresser but it would have to be charged to our credit card until the broken dresser could be picked up.

Price Adjustment Day

I get a phone call this morning I find out the footboard and dresser will be coming on two separate days next week (at least the footboard is coming first). I had to ask about the price adjustment. The price didn’t sound right to me so I checked with Sandy after the call and found out it was off by about 300 dollars.
Sandy phones back and the “D�cor Consultant” and she looked at the prices again and realized her mistake. She says to Sandy:

“Well, I’m going to have to take this to the backroom and try to figure it all out. This takes me off the floor for a long time and the only way I make money is when I’m selling”

It appears this “D�cor Consultant” has figured out how to game the system. After she has our money there really is no value to her providing us service even when she makes a mistake (Sandy called her manager and the manager apologized for the comment).

My Point

It doesn’t matter if you are tracking the number of unit tests written or amount of sales for a sales person, as soon as you tie your metrics to compensation they will become useless.

Oh ya, and avoid the “D�cor Consultants” at Sears.

May 27, 2006

Re: Do you use source control?

Filed under: Code — mikesdump @ 3:53 am

Mike over at Sideline asked an interesting question and it is one we have debated before. The question was, “Do you use source control”? I believe using source control is one of the practices that separate hobbyist from professionals.
The first programming job I had out of school was in a three-person shop. The owner, who believed that “GOTO” made your code more efficient, thought it would be a good idea to introduce source control (using Visual Source Safe). His reasoning was because the software we were developing was so valuable it was important to keep the source code someplace where it was encrypted and the employees couldn’t steal it (seriously, I think he was insane). I’m lucky I escaped with the little amount of sanity I have today.
Regardless of my previous employer’s motivations for using source control like Mike said most developers would agree using source control is a no brainer.
� It allows you to share code amongst a team
� It allows you to find out who made a change.
� It allows you discover what new functionality has been developed in other areas of an application (i.e. a common library)
� If all else fails you can rollback to a previous version
� If source control is being used it is probably being backed up (not usually the case with individual workstations)
So Mike’s second question:


Which makes me wonder about source control. If it’s so valuable, then why don’t most “good” developers use it at home?


“Good” is relative. I have been in the industry long enough to know what a command prompt is. Surviving this long could be a complete fluke but for the sake of argument let’s say I’m “good”.
In the past 8 years I have used source control on home projects twice. Both times the motivation was similar. I was working with other developers outside of work and I was interested in trying a different source control program (first CVS and more recently SubVersion).
On all the other projects I have worked on at home they have mainly been geared around learning a new language, trying out a class I never used before or writing a small application to work through a problem. On these projects:
� I work alone
� I don’t care about changes between file revisions
� I’m the one who wrote the code so I should understand it
� I will never rollback a file on a personal project (I only look forward never back)
� I back up my source code on a “fairly” regular basis
At home when working on a project for myself I’m a hobbyist not a professional. If I was a professional at home I would have to finish what I start and have to find a way to get paid for some of this.

March 9, 2006

VSS: File Renaming

Filed under: Code — mikesdump @ 12:27 pm

I have been using source control for about 7 years now. The time I have spent has almost equally been split between StarTeam and VSS (not sure if this is the right URL). Although I can’t remember many of the features in StarTeam I remember the feeling. It felt warm and safe like
sitting on a beach at a fancy resort. Where VSS feels like you are sitting on ice at the North Pole wearing nothing but your birthday suit.

In the past I have always avoided renaming files in a project under source control because I didn’t want to lose the history. Renaming
files that are under source control would not be required that often if people didn’t check in “Form1.vb” but that is another story.

The other day I had enough of Form1.vb staring back at me in the project that I was working on so I decided to act. Here is what I did:

1) Opened up the VSS browser
2) Found the evil Form1.vb and all of its resx files and renamed to something more suitable (Form2 was the first thing that came to mind
but I settled on MainForm since this is the only form in the project)
3) Started the project in VS.NET and checked out the project and Form1.vb
4) Renamed the file
5) Acknowledged the five warnings on how the world can end by renaming a file and one warning on how “MainForm” already existed under source control.
6) Check in the project and “new” MainForm

I opened my newly named form and it appeared to be intact. I checked
out the file, made a trivial change and checked it in and check the
history it all looked good.

I’m sure there are people out there saying didn’t you read the freak’in
help on how to do this? And my answer of course would be, NO. If there
were help on how to deal with this I would hope a technical writer
would say, “Hey, this sounds like a real pain in the ass. Do you think
maybe this should be enhanced? Renaming files is something that might
happen� from time-to-time”.

As much as I hated the process I was pretty happy this worked until tonight.

At home I setup Subversion a little
while ago. I have TortoiseSVN
installed which integrates with Windows Explorer and I have Ankhsvn installed for VS.NET 2005 integration. A
few nights ago I checked in my first real project and realized I forgot
to rename one folder within the project. I went into VS.NET, renamed
the folder, checked in the project and BANG! All the files under the
old folder were under the new one like I would expect and I could even
go into the repository browser to see a graph that showed at what
version the folder name changed.

So if you have tips on how to easily change file names that are under
VSS control you could leave them as a comment. But, what would be more
appreciated is marketing propaganda on why a development shop should
dump VSS for subversion 🙂

February 22, 2006

Complex Software

Filed under: Code,Links — mikesdump @ 11:43 am

So I started reading Domain-Driven Design: Tackling Complexity in the
Heart of Software

tonight and I have only made it through the first couple of pages
before saying, “Argh”!

Here is my issue:

…Although all three projects delivered useful software, only one
achieved its ambitious objectives and produced complex software that
continued to evolve to meet the ongoing needs of the organization…

If you finish writing an application and sit back and say, “Wow, that’s
a complex piece of software”. Would you feel good about that? Is
something you’d brag about? I’d hope not.

At my previous job we set yearly goals with our managers. One goal my
manager set for me was to develop complex software. I didn’t think all
that much of it at the time because I thought she was just trying to
make my goal non-specific to my current project. Part of the process
was my manager reviewed the goals with her manager (if it sounds like a
lot of red tape it was). Anyways, her manager laughed when reading that
particular goal and said, “We don’t want anyone writing complex
software we want people solving complex problems”.

The goal of any software developer should be to develop the simplest
solution possible for a business problem no matter how complex the problem is.
By simple I don’t mean no structure or throw out all ideas of good
design.

Simple software is easier to support and for new developers to jump in
and become productive sooner. Sure sometimes complicated problems
require more complex solutions but I think how simple an application is
should be a measurement of success not how complex.

February 8, 2006

Document-Driven Documentation

Filed under: Code,Links — mikesdump @ 12:35 pm

Documents are the only “real” deliverable when working on a software
project right? Documents like the CYAD (Cover Your Ass Document), HTCS
(Hose The Customer Specification) and last but not least the critical
IDMWIWBYROOMBID (It Doesn’t Matter What I Write Because You’ll Run Out
Of Money Before I Deliver) Document.

The people involved at Waterfall 2006 know what is important when it
comes to developing software projects. What got me excited (not
something most people should see) was when I read about wordUnit.
Writing documentation because the “Methodology” say so is
challenging but wordUnit offers to help make sure your “useful” documents are
accurate. I’m not sure how it will work but I can’t wait to start using
it!

January 20, 2006

.NET Compact Framework – Updating the UI from a Worker Thread – Part Deux

Filed under: Code — mikesdump @ 2:14 pm

Just when you thought it was safe to enter the water, there it is.
Slowing the music gets louder (you’ll just have to imagine the Jaws
music at this point because I have no idea how to type it).

Then it strikes! BANG � right in the ass. Well, this one does sneak up on you anyways.

Another developer at work was running into a situation where the UI
needed to be updated from another thread but when that happened the
application appeared to lock up. I found it slightly amusing because
the day before I ran into the same problem and I posted my solution
here
.
When he tried the solution and it didn’t solve the problem I was a little confused.

After working with emulators for several years I know they can be buggy
and not like the real thing but I wasn’t ready to throw in the towel
yet. So I turned to my trusty magic wand and
after casting several spells, whala! The one piece of information
required was found here.

So we will start with the code from the previous post, which was a form in a smart client application.

Private workerThread As Thread
Private shuttingDown As Boolean
Private counter As Integer

Private Sub Form1_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load
workerThread = New Thread(AddressOf UseInvokeInsteadOfDirectlyUpdatingUI)
workerThread.Start()
End Sub

Private Sub Form1_Closed(ByVal sender As Object, ByVal e As System.EventArgs) Handles MyBase.Closed
shuttingDown = True
End Sub

Private Sub UseInvokeInsteadOfDirectlyUpdatingUI()
While shuttingDown = False
Me.Label1.Invoke(New EventHandler(AddressOf WorkerThreadPlayingNiceWithTheUI))
counter += 1
Thread.Sleep(500)
End While
End Sub

Private Sub WorkerThreadPlayingNiceWithTheUI(ByVal sender As Object, ByVal e As System.EventArgs)
Label1.Text = counter.ToString()
End Sub

Now instead of our application directly launching the form on start up
we will create a module with a “main” method (or a class with a
shared/static method) which creates and displays the form like so

Module Module1
Public Sub Main(args() as String)
Dim mainForm as new Form1()
mainForm.ShowDialog()
End Sub
End Module

If you try to run this in the emulator you will probably notice the
label never updates. If you put a break point in just before the
“Me.Label1.Invoke” call and step through the code you will notice the
application will appear to “hang” on the invoke method call. If you run
in debug mode and “pause” the application you will be brought to this
line

mainForm.ShowDialog()

This line is the biggest clue to the real issue. The only thing we have
changed is how the main form is being created right? Well kind of. If
you set the form as the startup object I believe it is doing something
like the following instead behind the scene:

Module Module1
Public Sub Main(args() as String)
Dim mainForm as new Form1()
Application.Run(mainForm)
End Sub
End Module

So what is going on?
ShowDialog does indeed show the form as we would expect but when it is
launched it is modal. From here on in this is all speculation on my
part but I believe the only UI messages that would be processed are
those on the form itself (say if you added a button to the form as
well).
When the invoke method is called it is adding a event message to the
Windows event queue which will be processed after the current method is
completed, which in our case after mainForm.ShowDialog returns. If the
application is started with Application.Run the method returns
immediately and the worker thread’s invoke calls can be processed
immediately.

To sum things up� don’t start the application with ShowDialog. Yep that
would be about it. I’m not really sure why we were doing that to begin
with. Just for the record the developer who is currently working on
this is completely innocent (in all honestly I wouldn’t be surprised if
the code was traced back to me� damn source control)

As I mentioned this is mainly speculation on my part based on what I
have seen. I haven’t read anything to suggest this is indeed what is
happening under the hood.

Comments are welcome!

January 15, 2006

.NET Compact Framework – Updating the User Interface from a Worker Thread

Filed under: Code — mikesdump @ 12:06 pm

Before you go ahead and update the UI from another thread using the .NET Compact Framework ask yourself the following:

“Self, do I like predictability or unpredictability?”

If you answered predictability then you can skip ahead to “What you should do after you got it wrong”. If you answered unpredictability then proceed to “Don’t be a moron, Mike already tried that”

Don’t be a moron, Mike already tried that
In my own defence I didn’t realize at the time the event was firing from a thread outside the main UI thread (I’m not sure if that is much of an excuse)

Anyways, you like unpredictability eh? I’m guessing when you are updating your UI from a worker thread you are doing something like this:

Private workerThread As Thread
Private shuttingDown As Boolean

Private Sub Form1_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load
workerThread = New Thread(AddressOf UpdateUIFromWorkerThread)
workerThread.Start()

End Sub

Private Sub Form1_Closed(ByVal sender As Object, ByVal e As System.EventArgs) Handles MyBase.Closed
shuttingDown = True

End Sub

Private Sub UpdateUIFromWorkerThread()
Dim counter As Integer


While shuttingDown = False
Label1.Text = counter.ToString()
counter += 1
Thread.Sleep(500)
End While

End Sub

What is happening here is a worker thread is created when this CE application first starts. The thread enters a loop that won’t end until the form is closed. In the loop a label is updated with the value of a counter which is incremented every half second.

When I tried this in the emulator it actually is predictable. Both attempts locked up the emulator and I wasn’t able to shutdown the application. I’ve seen more complicated applications updating the UI from a worker thread that weren’t so consistent.
In short, don’t update the UI from outside the main UI thread. UI controls are not thread safe.

What you should do after you got it wrong
There are many things you should be doing after getting it wrong the first time. The key to getting it right is completing the steps below in order.

1) Swear at your computer and/or CE device
2) Grab another beer (if you aren’t currently drinking that is another mistake)
3) Read the right freak’in documentation

Sure, you are thinking this is a simple problem. I just need to use that “control.invoke” thingy and all will be well. The answer is yes and no. The compact framework way is below.

Private workerThread As Thread
Private shuttingDown As Boolean
Private counter As Integer

Private Sub Form1_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load
workerThread = New Thread(AddressOf UseInvokeInsteadOfDirectlyUpdatingUI)
workerThread.Start()

End Sub

Private Sub Form1_Closed(ByVal sender As Object, ByVal e As System.EventArgs) Handles MyBase.Closed
shuttingDown = True

End Sub

Private Sub UseInvokeInsteadOfDirectlyUpdatingUI()
While shuttingDown = False
Me.Label1.Invoke(New EventHandler(AddressOf WorkerThreadPlayingNiceWithTheUI))
counter += 1
Thread.Sleep(500)
End While

End Sub

Private Sub WorkerThreadPlayingNiceWithTheUI(ByVal sender As Object, ByVal e As System.EventArgs)
Label1.Text = counter.ToString()
End Sub

There are only a couple small changes from the previous version of this code.

1) counter is no longer a local variable to the worker thread method (UseInvokeInsteadOfDirectlyUpdatingUI())
2) The worker thread method calls Me.Label1.Invoke which will call WorkerThreadPlayingNiceWithTheUI
3) WorkerThreadPlayingNiceWithTheUI uses the member level variable counter to update the label.

What gave me a little bit of grief was I was reading a post I found on invoke which would be fine for the desktop but didn’t work in the compact framework (I can’t recall for sure but I believe I got an ArguementException when attempting it this way).

On the desktop the invoke method is overloaded and you would be able to pass the value of “counter” to the method directly instead of making it a member variable. I would prefer this over declaring the counter at the class level but it doesn’t appear to be an option for the compact framework.

The second thing that got me is that the delegate must be of type EventHandler for the compact framework (also this is something this post told me not to do).

The last item to note in the MSDN documentation which I don’t think applies in this case is:

An important point to note is that you must call Application.DoEvents() in your code if you are updating the UI in the worker thread. Calling Application.DoEvents() will make sure that any events raised by the worker thread are processed by the UI thread.

Looking at the example on that page the UI thread was blocking for one second. Just before the sleep call it was calling Application.DoEvents() which would process any events waiting to be processed by the worker thread. Since in my example the UI thread isn’t blocking at any point the Invoke calls are completed as expected.

The moral of the story: Don’t just read the documentation, read the right documentation.

kick it on dotnetkicks.com

System Error &H80070005&

Filed under: Code — mikesdump @ 2:20 am

I was getting this really odd error when compiling a smart client application in VB.NET the other day.

system Error &H80070005&

I was just about to access my long term memory to try
and figure out the problem when I thought, “Hey , I just checked all of
this out of VSS perhaps something is read only that shouldn’t be”.

Sure enough, all the files in the bin and obj directories were checked
into VSS with the project. When I checked them out they were all read
only and the compiler couldn’t overwrite the files. You’d think VS.NET
would give a bit better of an error message though.

Next Page »

Blog at WordPress.com.