DaedTech

Stories about Software

By

What Technical Documents Should You Review?

Editorial Note: I originally wrote this post for the SmartBear blog.  You can check out the original here, at their site.  While you’re there, have a look at the posts by some of the other authors.

If you’re anything like me in your programming proclivities, there’s a kind of singular impatience that leaps into your mind around the subject of documentation.  On the consuming side, whether it’s an API or a product, you have a tendency to think to yourself, “I don’t want to read about it, I just want to start hacking away at it.”  On the flip side, when it comes to producing documentation, that seems an onerous process; you’ve already finished the work, so why belabor the point?

Those are my natural impulses, but I do recognize the necessity for producing and consuming documentation surrounding the work that we do.  Over the years, I’ve developed strategies for making sure I get it done when it needs to be done.  For instance, even as someone who makes part of my living writing and teaching, I still segment my days for the sake of efficiency; I have writing days and I have programming days.

In order for this work not to get shortchanged in your group, it’s important to develop similar strategies or commitment devices.  The work needs to get done, and it needs to get done well, or else it won’t be useful.  And peer review is a vital part of that process.  After all, you create process around peer review for code — the developers’ strategy for sanity checks and spreading of knowledge.  Doesn’t it stand to reason that you should also do this with the documents that you create around this process?

Let’s take a look at some documentation that your group may be producing, and explore the idea of having peer review to go along with it.  We’ll look at an answer to the question, “what technical documents should you review?”

Read More

By

Improve Your Code Review Game with NDepend

Editorial Note: I originally wrote this post for the NDepend blog.  You can check out the original here, at their site.  If you like posts about static analysis, have a look around while you’re there.

Code review is a subject with which I’m quite familiar.  I’m familiar first as a participant, both reviewing and being reviewed, but it goes deeper than that.  As an IT management consultant, I’ve advised on instituting and refining such processes and I actually write for SmartBear, whose products include Collaborator, a code review tool.  In spite of this, however, I’ve never written much about the intersection between NDepend and code review.  But I’d like to do so today.

I suppose it’s the nature of my own work that has made this topic less than foremost on my mind.  Over the last couple of years, I’ve done a lot of lone wolf, consultative code assessments for clients.  In essence, I take a codebase and its version history and use NDepend and other tools to perform extensive analysis.  I also quietly apply some of the same practices to my own code that I use for example purposes.  But neither of these is collaborative because it’s been a while since I logged a lot of time in a collaborative delivery team environment.

DevOpportunityCost

But my situation being somewhat out of sync with industry norms does not, in any way, alter industry norms.  And the norm is that software development is generally a highly collaborative affair, and that most code review is happening in highly collaborative environments.  And NDepend is not just a way for lone wolves or pedants to do deep dives on code.  It really shines in the group setting.

NDepend Can Automate the Easy Stuff out of Code Review

When discussing code review, I’m often tempted to leave “automate what you can” for the end, since it’s a powerful point.  But, on the other hand, I also think it’s perhaps the first thing that you should go and do right out of the gate, so I’ll mention it here.  After all, automating the easily-automated frees humans up to focus on things that require human intervention.

It’s pretty likely that you have some kind of automation in process for enforcing coding standards.  And, if you don’t, get some in place.  You should not be wasting time at code review with, “you didn’t put an underscore in front of that field.”  That’s the sort of thing that a machine can easily figure out, and that many, many plugins will figure out for you.

The advantages here are many, but two quick ones bear mentioning here.  First is the time-savings that I’ve discussed, and second is the tightening of the feedback loop.  If a developer writes a line of code, forgetting that underscore, the code review may not happen for a week or more.  If there’s a tool in place creating warnings, preventing a commit, or generating a failed build, the feedback loop is much tighter between undesirable code and undesirable outcome.  This makes improvement more rapid, and it makes the source of the feedback an impartial machine instead of a (perceived) judgmental coworker.

Read More

By

Should You Review Requirements and Design Documents?

Editorial Note: I originally wrote this post for the SmartBear blog.  You can check out the original here, at their site.  While you’re there, have a look around at posts and knowledge from other authors.

I remember working in a shop that dealt with medical devices some years back.  I can’t recall whether it was the surrounding regulatory requirements or something about the culture at this place, but there was a rule in place that required peer review of everything.

Naturally, this meant that all code was reviewed, but it went beyond that and extended to any sort of artifact produced by the IT organization.  And, since this was a waterfall shop, that meant review (and audit-trails of approval) of the output of the requirements phase and the design phase, which meant requirements and design documents, respectively.  I can thus recall protracted meetings where we sat and soberly reviewed dusty documents that made proclamations about what “the system” shall and shan’t do.  We also reviewed elaborate sequence, flow, hierarchy, and state design artifacts that were probably obsolete before we even reviewed them.

If I make this activity sound underwhelming in its value, that’s because I routinely felt underwhelmed by its value.  It was a classic case of process over common sense, of ceremony over pragmatism.  Everyone’s attention wandered, knowing that all bets would be off once the development started.  Sign-offs were a formality — half-hearted and cursory.

But is it worth throwing the baby out with the bathwater?  Should the fact that waterfall shops waste time on and around these documents stop you from producing them and subsequently reviewing them?  Is it worth reviewing requirements and design documents?

LotsLeftToDo

Read More

By

Targeted Code Reviews in Regulated Industries

Editorial Note: I originally wrote this post for the SmartBear blog.  You can check out the original here, at their site.  While you’re there, check out the work of the other authors writing for them as well.

For a lot of people out there developing software, life is pretty simple.  I say this not because there’s anything simple about software development, but because life around the practice of software development is simple.  You come in around 9, spend the day doing what the software needs to have done to it, and you go home at 5.  Maybe every now and then you stay late some days to make a push.

As organizations get bigger and more specialized, however, the outlook starts to change.  Growth brings larger and larger headcount, which, in turn, means more communication channels and general, bureaucratic overhead.  Growth also brings more outsider scrutiny and general public interest, particularly as companies go public and make headlines.  Such organizations start to become regulated.

Clipboard

Simply put, a regulated organization is one in which the government takes an interest.  Legislation about how the organization must behave is created, enacted, and enforced, the latter often coming in the form of check-ups, inspections, or audits.  Large companies may find themselves regulated in ad hoc fashion, or it may happen due to their size and public influence.  Other companies are regulated at any size, simply by virtue of their industry.  This latter designation applies to the finance, energy, healthcare, and defense industries, to name a few.

The Productivity Impact of Regulation

However your company comes to be regulated, the impact on you, as a software developer, is noticeable.  You have to do stuff with which your peers at other organizations needn’t bother.  You need to follow certain protocols for database access or document your code in certain ways.  Often times, and at larger organizations, this takes on a “death by a thousand cuts” status in your life, and it starts to feel as though you do a lot more box-checking than software development.

This, in spite of the importance of complying with this regulations, is an untenable state of affairs for a group.  To put a point on it with hyperbole, one surefire way to have your software comply with all regulations is not to write any software.  And, while that’s clearly never the actual mission of your company, it can sometimes feel that way as regulation compliance starts to swallow your time.

Read More

By

Reviewing Strangers’ Code on Github

Editorial Note: I originally wrote this post for the SmartBear blog.  You can check out the original here, at their site.  While you’re there, check out some of the pieces by their other authors.

I make part of my living these days as an IT management consultant, and in this capacity, I’ve developed an interesting niche: evaluation of codebases.  Specifically, an organization’t management will bring me in to spend a week or two looking through a codebase, sizing it up, and making recommendations for what to do with it going forward (e.g. “stay the course, rework the architecture, targeted training, scrap it, etc.”)

As you might imagine, this part of my practice leads me to looking at and quickly grokking a lot of unfamiliar code.  Every few weeks, I’m squinting at strange classes, running static analysis tools, and making lists of assumptions and questions to ask the development team.  And I’ve found that this practice has benefits to me beyond helping me earn my living.  I’d argue that it makes me a better programmer.

Consider the opposite situation — one that describes an enormous cross section of industry developers.  They come in to work each day and deal with the same codebase.  This continues day in and day out for weeks, months, or even years.

This year, my wife and I are hoping to make a visit to the Galapagos Islands, which are noteworthy for the uniqueness of the wildlife there.  The animals living there have been isolated from the wider world of fauna for millions of years, and the result is that they’ve developed unique and unusual characteristics that cannot be found anywhere else.  This is what tends to happen to codebases in shops where the majority of developers work in relative isolation.  A bubble forms, and practices drift toward the unusual.

bird

For an individual, this isolation tends to put a damper on skill acquisition and can even be career limiting.  It’s the polar opposite of the situation in which I find myself — constantly immersed in unfamiliar code.  So how can you remedy the isolation if your professional life shows you the same code in day in and day out?  (Without drastic career moves, that is).  Well, the dead simplest thing I can think of is to seek out and review other people’s code.  And to do that, there’s no better place to go than Github.

Here’s what you can do.  Every few weeks or so, poke around idly on Github, searching for random codebases in your language of choice.  Big or small, popular or niche, active or forgotten — it really doesn’t matter much.  They just need to be different and new.

Once you’ve found one (and just about any one will do), clone it and get the code locally on your machine.  Open it up in your IDE/editor/environment of choice, and start looking around.  If you start to perform this exercise with some regularity, here are some benefits that you can expect, in my experience.

Read More