Stories about Software


You Can Use GhostDoc’s Document This with JavaScript

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, have a look at GhostDoc for your code documentation and help file generation needs.

If you haven’t lived in a techie cave the last 10 years, you’ve probably noticed JavaScript’s rise to prominence.  Actually, forget prominence.  JavaScript has risen to command consideration as today’s lingua franca of modern software development.

I find it sort of surreal to contemplate that, given my own backstory.  Years (okay, almost 2 decades) ago, I cut my teeth with C and C++.  From there, I branched out to Java, C#, Visual Basic, PHP, and some others I’m probably forgetting.  Generally speaking, I came of age during the heyday of object oriented programming.

Oh, sure I had awareness of other paradigms.  In college, I had dabbled with (at the time) the esoteric concept of functional programming.  And I supplemented “real” programming work with scripts as needed to get stuff done.  But object oriented languages gave us the real engine that drove serious work.

Javascript fell into the “scripting” category for me, when I first encountered it, probably around 2001 or 2002.  It and something called VBScript competed for the crown of “how to do weird stuff in the browser, half-baked hacky languages.”  JavaScript won that battle and cemented itself in my mind as “the thing to do when you want an alert box in the browser.”

Even as it has risen to prominence and inspired a generation of developers, I suppose I’ve never really shed my original baggage with it.  While I conceptually understand its role as “assembly language of the web,” I have a hard time not seeing the language that was written in 10 days and named to deliberately confuse people.

Read More


CodeIt.Right Rules, Explained Part 3

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 CodeIt.Right and see how you can automate checks for and enforcement of these rules.

In what has become a series of posts, I have been explaining some CodeIt.Right rules in depth.  As with the last post in the series, I’ll start off by citing two rules that I, personally, follow when it comes to static code analysis.

  • Never implement a suggested fix without knowing what makes it a fix.
  • Never ignore a suggested fix without understanding what makes it a fix.

It may seem as though I’m playing rhetorical games here.  After all, I could simply say, “learn the reasoning behind all suggested fixes.”  But I want to underscore the decision you face when confronted with static analysis feedback.  In all cases, you must actively choose to ignore the feedback or address it.  And for both options, you need to understand the logic behind the suggestion.

In that spirit, I’m going to offer up explanations for three more CodeIt.Right rules today.

Read More


Exploring the Tech Debt In Your Codebase

Editorial note: I originally wrote this for the NDepend blog.  You can check out the original here, at their site.  While you’re there, check out the tech debt features in the newest version of NDepend.

Recently, I posted about how the new version of NDepend lets you compute tech debt.  In that post, I learned that I had earned a “B” out of the box.  With 40 minutes of time investment, I could make that an “A.”  Not too shabby!

In that same post, I also talked about the various settings in and around “debt settings.”  With debt settings, you can change units of debt (time, money), thresholds, and assumptions of working capacity.  For folks at the intersection of tech and business, this provides an invaluable way to communicate with the business.

But I really just scratched the surface with that mention.  You’re probably wondering what this looks like in more detail.  How does this interact with the NDepend features you already know and love?  Well, today, I’d like to take a look at just that.

To start, let’s look at the queries and rules explorer in some detail.

Introducing Quality Gates

Take a look at this screenshot, and you’ll notice some renamed entries, some new entries, and some familiar ones.

In the past, “Code Smells” and “Code Regressions” had the names “Code Quality” and “Code Quality Regression,” respectively.  With that resolved, the true newcomers sit on top: Quality Gates and Hot Spots.  Let’s talk about quality gates.

Read More


Ghost Doc Says the Damndest Things

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, have a look at GhostDoc, which can help both with code comment maintenance and the generation of help documentation.

Some years ago, I was doing work for some client or another.  Honestly, I have no recollections of specifics with the exception of a preference for exhaustive commenting.  Every class, every method, every property, and every field.

Of course, I didn’t learn this at first.  I didn’t even learn it in a reasonable time frame.  Instead, I learned it close to handover time.  And so things got a little desperate.

Enter GhostDoc, My Salvation

Now, depending on your perspective, you might scold me for not diligently commenting all along.  I will offer the explanation that the code had no public component and no intended APIs or extensions.  It also required no “why” types of explanations; this was simple stuff.

The client cited policy.  “We comment everything, and we’re taking over this code, so we want you to do the same.”  Okie dokie.

Now, I knew that in a world of code generation and T4 templates, someone must have invented a tool that would generate some sort of comments or another.  At the time, a quick Google search brought me to a saving grace: the free tool GhostDoc.

While it did not allow me to carpet bomb my code with comments in a single click (and understandably so), it did allow me to do it for entire files at a time.  Good enough.  I paid my non-commenting penance by spending an hour or so commenting this way.

And do you know what?  It generated pretty respectable comments.  I recall feeling impressed because I expected empty template comments.  Instead, GhostDoc figured out how to string some verbs and nouns together.

Read More


Detecting Performance Bottlenecks with NDepend

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 NDepend and see what it can tell you about your code.

In the past, I’ve talked about the nature of static code analysis.  Specifically, static analysis involves analyzing programs’ source code without actually executing them.  Contrast this with runtime analysis, which offers observations of runtime behavior, via introspection or other means.

This creates an interesting dynamic regarding the idea of detecting performance issues with static analysis.  This is because performance is inherently a runtime concern.  Static analysis tends to do its best, most direct work with source code considerations.  It requires a more indirect route to predict runtime issues.

For example, consider something simple.

With a static analyzer, we can easily look at this method and say, “you’re dereferencing ‘theService’ without a null check.”  However, it gets a lot harder to talk definitively about runtime behavior.  Will this method ever generate an exception?  We can’t know that with only the information present.  Maybe the only call to this in the entire codebase happens right after instantiating a service.  Maybe no one ever calls it.

Today, I’d like to talk about using NDepend to sniff out possible performance issues.  But my use of possible carries significant weight because definitive gets difficult.  You can use NDepend to inform reasoning about your code’s performance, but you should do so with an eye to probabilities.

That said, how can you you use NDepend to identify possible performance woes in your code?  Let’s take a look at some ideas.

Read More