DaedTech

Stories about Software

Aug
31

By

.NET Code Documentation So Easy It’s an Afterthought

Category: .NET Tags: , , , |

Editorial note: I originally wrote this post for the SubMain blog.  You can check out the original here, at their site.  While you’re there, take a look at GhostDoc if you want automated documentation for your API.

Though I’ll talk today about .NET code documentation, I want to start further back than that. And by “that,” I mean further back than .NET. I realize that may date me somewhat, but please bear with me.

Most things in the programming world date back further than you’d think. For a dramatic example of this, consider functional programming. All the rage today, it actually dates back to the 60s in practice and 30s in theory. Speculating about the reason for temporal myopia would go beyond the scope of this post, but understand that this tendency toward myopia does exist.

With that in mind, let’s talk about some GUI builders.

A Tale of Two GUI Builders

Now we get to the part that predates .NET. I’m going to reach back into my early career and compare my relatively simultaneous experience with two GUI building technologies.

First, I encountered Swing, a Java GUI toolkit. While Swing did not include a GUI builder at the time, my project packaged it with one. I cannot remember its name for the life of me, but this thing was a train wreck. Moving controls around on a form caused the spewing of improbable amounts of code into my Java classes. Attaching handlers to GUI events only half worked, requiring wire up by hand. I had such struggles with it that I gave up and just hand-coded everything in Java.

Shortly after working on that project, I found myself saddled with a VB6 application. At the time, .NET actually existed, but nobody had ported this thing to it. So I used VB6. And I loved it.

That probably sounds as weird to hear as it feels to type, but there it is. Compared to my experience with Swing and its nightmarish GUI builder, this was a refreshing summer breeze. I could move controls around to my heart’s content, wire up events easily, and get stuff done.

Read More

Aug
31

By

Getting Started with Behavior-Driven Development

Category: Language Agnostic Tags: , , , | 4 Comments

Editorial note: I originally wrote this post for the TechTown blog.  You can check it out here, at their site.  While you’re there, have a look around at the different training courses they offer.

You’ve probably heard of behavior-driven development (BDD).  However, if you’ve never practiced it, you may perceive it as one of many in a nebulous cloud of acronyms.  We have BDD, TDD, DDD, and ATDD.  All of these have a “D” standing for “driven” and another one standing for either “development” or “design.”  Apparently, we software developers really like things to drive us.

I won’t engage in a full “DD” taxonomy here, as this post concerns itself with behavior-driven development only.  But we will need to take a tour through one of these in order to understand BDD’s motivations and backstory.

Behavior-Driven Development Origins and Motivation

To understand BDD, we must first understand test-driven development (TDD).  Luckily, I wrote a recent primer on that.  To recap briefly, TDD calls for you to address every new thing you want your production code to do by first writing a failing test.  Doing this both verifies that the system currently lacks the needed functionality and gives you a way to later know that you’ve successfully implemented it.

With TDD, you deal in microtests.  These distinguish themselves by being quite specific and granular.  For instance, you might assert that you get a null reference exception when invoking a method with a null parameter.  You’ll pardon non-technical project stakeholders for a distinct lack of interest in these microtests.

BDD evolved from asking the question, “Why don’t we do this for tests that the business might care about?”  It follows the same philosophical approach and logic.  But instead of worrying about null parameters and exceptions, these tests address the system’s behavior at the capability or feature level.

Behavior-driven development follows the TDD cadence: express a current system deficiency with a failing test. But this time the failing test is, for example, when I deposit money into my checking account, I can see the reflected balance.  Work then proceeds on that feature until the test passes.  At this time, the team considers the card complete.

Read More

Aug
29

By

Is There a Correct Way to Comment Your Code?

Category: Language Agnostic Tags: , , | 50 Comments

Editorial note: I originally wrote this post for the NDepend blog.  You can check out the original here, at their site.  While you’re there, take a look at all of the visualizations and metrics that you can get about your codebase.

Given that I both consult and do a number of public things (like blogging), I field a lot of questions.  As a result, the subject of code comments comes up from time to time.  I’ll offer my take on the correct way to comment code.  But remember that I am a consultant, so I always have a knee-jerk response to say that it depends.

Before we get to my take, though, let’s go watch programmers do what we love to do on subjects like this: argue angrily.  On the subject of comments, programmers seem to fall roughly into two camps.  These include the “clean code needs no comments” camp and the “professionalism means commenting” camp.  To wit:

Chances are, if you need to comment then something needs to be refactored. If that which needs to be refactored is not under your control then the comment is warranted.

And then, on the other side:

If you’re seriously questioning the value of writing comments, then I’d have to include you in the group of “junior programmers,” too.  Comments are absolutely crucial.

Things would probably go downhill from there fast, except that people curate Stack Overflow against overt squabbling.

Splitting the Difference on Commenting

Whenever two sides entrench on a matter, diplomats of the community seek to find common ground.  When it comes to code comments, this generally takes the form of adages about expressing the why in comments.  For example, consider this pithy rule of thumb from the Stack Overflow thread.

Good programmers comment their code.

Great programmers tell you why a particular implementation was chosen.

Master programmers tell you why other implementations were not chosen.

Jeff Atwood has addressed this subject a few different times.

When you’ve rewritten, refactored, and rearchitected your code a dozen times to make it easy for your fellow developers to read and understand — when you can’t possibly imagine any conceivable way your code could be changed to become more straightforward and obvious — then, and only then, should you feel compelled to add a comment explaining what your code does.

…

Junior developers rely on comments to tell the story when they should be relying on the code to tell the story.

And so, as with any middle ground compromise, both entrenched sides have something to like (and hate).  Thus, you might say that whatever consensus exists among programmers, it leans toward a “correct way” that involves commenting about why.

Read More

Aug
28

By

How to Evaluate Software Quality from Source Code

Category: Language Agnostic Tags: , | 6 Comments

Editorial note: I originally wrote this post for the Stackify blog.  You can check out the original here, at their site.  While you’re there, take a look at their Retrace offering that gives you everything you need to track down production issues.

I’ll understand if you read the title of this post and smirked.  I probably would have done so, opening it up only to see what profound wisdom awaited me.  Review the code, Captain Obvious.  

So yes, rest assured, I understand the easy assumption that one can ascertain a codebase’s quality by opening it up and starting to review it.  But what does this really tell you?  What comes out of this activity?  Simply put, your opinion of the codebase’s quality comes out of this activity.

I actually have a consulting practice doing custom static analysis on client codebases.  I help managers and executives make strategic decisions about their applications.  And I do this largely by treating their code as data and building numerically based cases.

Initially, the idea for this practice arose out of some observations I’d made a while back.  I watched consultants tasked with critical evaluations of codebases, and I found that they did exactly what I mentioned in the first paragraph.  They reviewed it, operating from the premise, I’m an expert, so I’ll record my anecdotal impressions and offer them as evidence.  That put a metaphorical pebble in my shoe and bothered me.  So I decided to chase a more empirical concept of code quality with my practice.

Don’t get me wrong.  The proprietary nature of source code and outcome data in the industry makes truly scientific experiments difficult.  But I can still automate the inquiries and use actual, relative data to compare properties.  So from that perspective, I’ll offer you more data-driven ways to evaluate software quality from source code.

Read More

Aug
27

By

Scale Your Freelancing: Hiring Others

Category: You Asked For It Tags: , , | 7 Comments

Last week, I answered a composite reader question about everyone’s favorite subject: taxes.  This week, I’ll build on that with another composite question.  This time about how to scale freelancing work that you might do.

I’ve gotten a few different questions about this over the last several months.  I’ll try to cover everything you all have asked by answer this composite question.

Freelancing is going well enough, but now I’ve got a spike in work that will be more than I can probably do on my own.  I’ll need to hire someone, somehow, to do something.  How does that work?

It’s understandable to wonder this.  Speaking from my own experience and what I’ve heard from many others, you’ll probably have your own freelancing practice or side hustle for a long time before this comes up.  Or, it might never come up, and you still have a rich happy professional life.

But when it does come up, it’ll probably happen quickly.  And, you’ll be swamped when it does, since, by definition, you’re looking to hire due to too much work for yourself.  So it’s good to at least have a concept of how this works ahead of time.

Caveats Again

As I mentioned in the last post, I am neither lawyer nor accountant.  I’ve hired subs and done a lot of business this way, but I am not a professional advisor.  What you’re getting here is my best understanding and things that have worked for me in the past.

Use the advice here to orient yourself and get a feel for how this works.  But before you actually go execute this stuff, you should contact your lawyer and accountant to verify that it’s right and that it makes sense for your situation.

And, once again, a lot of this may be US specific, but I hope non-US readers can get something out of it as well.

Can I just pay someone, the way I pay the neighbor kid to shovel my driveway?

This is the first thing that might occur to you.  You’ve got to deliver 4 modules by the end of the week, and you can only possibly deliver two of them.  Can’t you just offer a fellow developer $1,000 or whatever in exchange for her doing the other two?  Seems simple, and it should be simple, you think.  That’s what I thought.  And it would actually be simple if not for the tax man.

Think of the kid you give $10 to shovel your driveway.  Seems innocent enough and like pure commerce in action, right?  Wrong.  In the first place, you’re probably technically violating some kind child labor law and possibly running afoul of minimum wage laws.  But, even if that little scamp were 18 and of legal working age, this would still represent an illegal transaction because he’s almost certainly not making a note of that $10 of income so that he can report it on his tax return.

So now, you can’t “just pay someone.”

Read More

« Older Posts
Newer Posts »