DaedTech

Stories about Software

Nov
3

By

DaedTech Digest: Static Analysis, Doco and Dependency Death Stars

Category: Digests Tags: , , , , |

Happy Friday, everybody.  I’m still figuring this digest thing out, so please bear with me.  But no matter how I iterate, what you’ll get is an aggregated link to posts that I’ve written for my Hit Subscribe business.

I’m thinking I’ll do picks each week as well as the digests.  You know how podcast panelists do “picks” at the end of a lot of podcasts?  I’ll give you some picks each week.  At least, unless this turns out to be a bad idea, in which case, I’ll stop.

Picks

  • Jogging without headphones.  For years, I’ve always doubled up on productivity by listening to podcasts or audio books while jogging, if not watching Pluralsight courses.  But recently a terrible pair of bluetooth headphones (seriously, don’t buy them — shop around for a competitor) broke, and I just went jogging with my thoughts.  It’s been a huge boost to the amount of creative thinking I do in a week.
  • I cannot rave enough about payroll service, Gusto.  If you need to run payrolls for your business, these guys make it seriously easy, even paying taxes for your automatically.  Before I switched, I’d been using Intuit’s online payroll, which was the user experience equivalent of a grizzly bear carrying a raccoon in a backpack and both of them are mauling you.  Gusto restored my faith in humanity.
  •  Every now and then, I get nostalgic for computer games from my childhood.  When I do, abandonia usually has me covered.

The Post Digest

And now, the post digest.

  • I write a lot of posts about static analysis, since it’s something of a specialty of mine.  Here’s another primer I did about it for TechTown training.  In it, I evangelized a bit, encouraging readers to look past the really dull name and see that underneath it lies a cool concept.
  • Speaking of static analysis, I wrote a post for NDepend entitled “Code Quality Metrics: Separating the Signal from the Noise.”  There’s a lot of reductionist code metrics out there, so I did my part to add some nuance to the world.
  • For SubMain, I wrote a post taking you through different documentation tool options that programmers have.  User manuals, release notes, and all the traditional stuff, but then also new approaches that generate documentation automatically, at least for a starting point.
  • In another NDepend post, I talk about a novel way to settle the inevitable squabbles among a development team.  Make your arguments, and then prove them visually, using automated tooling to paint pictures of your codebase.  My personal favorite for proving a point has always been the dependency death star.
  • And, finally, I wrote a post for Monitis trying to get a little more specific around the generalized and often hype-y term, “big data.”  This post took a longer view, tracing a history of the concept back to the early days of Java and .NET.

 

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

Jul
12

By

Add Custom Content to Your Documentation

Category: Uncategorized 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, have a look at GhostDoc not only to help you with comment management and generation, but also to help you construct automated help documentation.

For the last several years, I’ve made more and more of my living via entrepreneurial pursuits.  I started my career as a software developer and then worked my way along that career path before leaving fulltime employment to do my own thing.  These days, I consult, but I also make training content, write books, and offer productized services.

When you start to sell things yourself, you come to appreciate the value of marketing.  As a techie, this feels a little weird to say, but here we are.  When you have something of value to offer, marketing helps you make interested parties aware of your offer.  I think you’d like this and find it worth your money, if you gave it a shot.

In pursuit of marketing, you can use all manner of techniques.  But today, I’ll focus on a subtle one that involves generating a good reputation with those who do buy your products.  I want to talk about making good documentation.

The Marketing Importance of Documentation

This probably seems an odd choice for a marketing discussion.  After all, most of us think of marketing as what we do before a purchase to convince customers to make that purchase.  But repeat business from customer loyalty counts for a lot.  Your loyal customers provide recurring revenue and, if they love their experience, they may evangelize for your brand.

Providing really great documentation makes an incredible difference for your product.  I say this because it can mean the difference between frustration and quick, easy wins for your user base.  And, from a marketing perspective, which do you think makes them more likely to evangelize?  Put yourself in their shoes.  Would you recommend something hard to figure out?

For a product with software developers as an end user, software documentation can really go a long way.  And with something like GhostDoc’s “build help documentation” feature, you can notch this victory quite easily.  But the fact that you can generate that documentation isn’t what I want to talk about today, specifically.

Instead, I want to talk about going the extra mile by customizing it.

Read More

Apr
13

By

Elements of Helpful Code Documentation

Category: Language Agnostic 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, check out GhostDoc, which can automatically generate help files for you.

If you spend enough years writing software, sooner or later, your chosen vocation will force you into reverse engineering.  Some weird API method with an inscrutable name will stymie you.  And you’ll have to plug in random inputs and examine the outputs to figure out what it does.

Clearly, this wastes your time.  Even if you enjoy the detective work, you can’t argue that an employer or client would view this as efficient.  Library and API code should not require you to launch a mystery investigation to determine what it does.

Instead, such code should come with appropriate documentation.  This documentation should move your focus from wondering what the code does to contemplating how best to leverage it.  It should make your life easier.

But what constitutes appropriate documentation?  What particular characteristics does it have?  In this post, I’d like to lay out some elements of helpful code documentation. Read More

Feb
7

By

Comments in Clean Code? Think Documentation

Category: Language Agnostic Tags: , | 15 Comments

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 for your documentation needs.

Second Editorial Note: I recently appeared on the Ruby Rogues podcast and was interviewed by Paysa.  If you’re interested, check both of them out!

Notwithstanding some oddball calculator and hobby PC hacking, my first serious programming experience came in college.  A course called “Intro to C++” got us acquainted with arrays, loops, data structures and the like.  Given its introductory nature, this class did not pose a particularly serious challenge (that would come later).  So, with all of the maturity generally possessed by 18 year olds, we had a bit of fun.

I recall contests to see how much application logic we could jam into the loop conditions, and contests to see how much code could be packed onto one line.  These sorts of scavenger hunt activities obviously produced dense, illegible code.  But then, that was kind of the point.

Beyond these silly hijinks, however, a culture of code illegibility permeated this (and, I would learn later) other campuses.  Professors nominally encouraged code readability.  After all, such comments facilitated partial credit in the event of a half-baked homework submission.  But, even still, the mystique of the ingenious but inscrutable algorithm pervaded the culture both for students and faculty.  I had occasion to see code written by various professors, and I noticed no comments that I can recall.

Professionalism via Thoroughness

When I graduated from college, I carried this culture with me.  But not for long.  I took a job where I spent most of my days working on driver and kernel module programming.  There, I noticed that the grizzled veterans to whom I looked up meticulously documented their code.  Above each function sat a neat, orderly comment containing information about its purpose, parameters, return values, and modification history.

This, I realized, was how professionals conducted themselves.  I was hooked.  Fresh out of college, and looking to impress the world, I sought to distinguish myself from my undisciplined student ways.  This decision ushered in a period of many years in which I documented my code with near religious fervor.

My habit included, obviously, the method headers that I emulated.  But on top of that, I added class headers and regularly peppered my code with line comments that offered such wisdom as “increment the loop counter until the end of the array.”  (Okay, probably not that bad, but you get the idea).  I also wrote lengthy readme documents for posterity and maintenance programmers alike.  My professionalism knew no bounds.

Read More

« Older Posts