Stories about Software


Generate Documentation from Your Build

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.

Before I get down to the brass tacks of how to do some interesting stuff, I’m going to spin a tale of woe.  Well, I might have phrased that a little strongly.  Call it a tale of corporate drudgery.

In any case, many years ago I worked briefly in a little department, at a little company that seemed to be a corporate drudgery factory.  Oh, the place and people weren’t terrible.  But the work consisted of, well, drudgery.  We ‘consulted’ in the sense that we cranked out software for other companies, for pay.  Our software plumbed the lines of business between client CRMs and ERPs or whatever.  We would write the software, then finish the software, then hand the software over, source code and all.

Naturally, commenting our code and compliance with the coding standard attained crucial importance.  Why?  Well, no practical reason.  It was just that clients would see this code.  So it needed to look professional.  Or something.  Didn’t matter what the comments said.  Didn’t matter if the standard made sense.  Compliance earned you a gold star and a move onto the next project.

As I surveyed the scene surrounding me, I observed a mountain of vacuous comments and dirty, but uniform code.

My Complex Relationship with Code Comments

My brief stay with (and departure from) this organization coincided with my growing awareness of the Software Craftsmanship movement.  Even as they copy and pasted their way toward deadlines and wrote comments announcing that while(x < 6) would proceed while x was less than 6, I became interested in the idea of self-documenting code.

Up to that point, I had diligently commented each method, file, and type I encountered.  In this regard, I looked out for fellow and future programmers.  But after one too many occasions of watching my own comments turn into lies when someone changed the code without changing the comments, I gave up.  I stopped commenting my code, focusing entirely on extractions, refactoring, and making my code as legible as possible.

I achieved an equilibrium of sorts.  In this fashion, I did less work and stopped seeing my comments become nasty little fibs.  But a single, non-subtle flaw remained in this absolutist approach.  What about documentation of a public (or internal) API?

Naturally, I tried to apply the craftsmanship-oriented reasoning unilaterally.  Just make the public API so discoverable as to render the issue moot.  But that never totally satisfied me because I still liked my handy help screens and Intellisense info when consuming others’ code.

And so I came to view XML doc comments on public methods as an exception.  These, after all, did not represent “comments.”  They came packaged with your deliverables as your product.  And I remain comfortable with that take today.

Read More


The Case for a Team Standard

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 CodeIt.Right and give it a try.

In professional contexts, I think that the word “standard” has two distinct flavors.  So when we talk about a “team standard” or a “coding standard,” the waters muddy a bit.  In this post, I’m going to make the case for a team standard.  But before I do, I think it important to discuss these flavors that I mention.  And keep in mind that we’re not talking dictionary definition as much as the feelings that the word evokes.

First, consider standard as “common.”  To understand what I mean, let’s talk cars.  If you go to buy a car, you can have an automatic transmission or a standard transmission.  Standard represents a weird naming choice for this distinction since (1) automatic transmissions dominate (at least in the US) and (2) “manual” or “stick-shift” offer much better descriptions.  But it’s called “standard” because of historical context.  Once upon a time, automatic was a new sort of upgrade, so the existing, default option became boringly known as “standard.”

In contrast, consider standard as “discerning.”  Most commonly you hear this in the context of having standards.  If some leering, creepy person suggested you go out on a date to a fast food restaurant, you might rejoin with, “ugh, no, I have standards.”

Now, take these common contexts for the word to the software team room.  When someone proposes coding standards, the two flavors make themselves plain in the team members’ reactions.  Some like the idea, and think, “it’s important to have standards and take pride in our work.”  Others hear, “check your creativity at the gate, because around here we write standard, default code.”

What I Mean by Standard

Now that I’ve drawn the appropriate distinction, I feel it appropriate to make my case.  When I talk about the importance of a standard, I speak with the second flavor of the word in mind.  I speak about the team looking at its code with a discerning attitude.  Not just any code can make it in here — we have standards.

These can take somewhat fluid forms, and I don’t mean to be prescriptive.  The sorts of standards that I like to see apply to design principles as much as possible and to cosmetic concerns only when they have to.

For example, “all non-GUI code should be test driven” and “methods with more than 20 lines should require a conversation to justify them” represent the sort of standards I like my teams to have.  They say, “we believe in TDD” and “we view long methods as code smells,” respectively.  In a way, they represent the coding ethos of the group.

On the other side of the fence lie prescriptions like, “all class fields shall be prepended with underscores” and “all methods shall be camel case.”  I consider such concerns cosmetic, since they concern appearance and not design or runtime behavior.  Cosmetic concerns are not important… unless they are.  If the team struggles to read code and becomes confused because of inconsistency, then such concerns become important.  If the occasional quirk presents no serious readability issues, then prescriptive declarations about it stifle more than they help.

Having standards for your team’s work product does not mean mandating total homogeneity.

Read More


Is Your Code Hard to Understand?

Editorial Note: I originally wrote this post for the Infragistics blog.

I’ve heard a bit of conventional wisdom in the software industry.  It holds that people will read a given line of code an order of magnitude more times than they’ll modify it.  Whether that wisdom results from a rigorous study or not, I do not know. But it certainly squares with my experience.  And it also seems to square with the experience of just about everyone else.

Accepting this wisdom as axiomatic, code readability becomes an important business concern.  If you optimize for ease of writing at the cost of ease of reading, your business will lose money.  Better to spend some extra time in writing your code to ensure that future readers have an easy go of it.  And easy for them means that they understand the code.

You know of obvious ways to promote reader understanding in code.  Don’t give variables cryptic names or names that cannot be pronounced.  Don’t write gigantic methods and classes.  Limit method parameters and local declarations.  Read through the code out loud to see if it seems clear.  These guidelines will bring you a long way toward readability.

But other, subtle concerns can also chip away at your code’s readability.  I’ll list some of these here, today.  These are generally C# specific, but some are more broadly applicable than that.  What all of them have in common is that they constitute sources of confusion for readers that may not seem immediately obvious.

Read More


Secrets of Maintainable Codebases

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, have a look at the tech debt quantification features of the new NDepend version.

You should write maintainable code.  I assume people have told you this, at some point.  The admonishment is as obligatory as it is vague.  So, I’m sure, when you heard this, you didn’t react effusively with, “oh, good idea — thanks!”

If you take to the internet, you won’t need to venture far to find essays, lists, and stack exchange questions on the subject.  As you can see, software developers frequently offer opinions on this particular topic.  And I present no exception; I have little doubt that you could find posts about this on my own blog.

So today, I’d like to take a different tack in talking about maintainable code.  Rather than discuss the code per se, I want to discuss the codebase as a whole.  What are the secrets to maintainable codebases?  What properties do they have, and what can you do to create these properties?

In my travels as a consultant, I see a so many codebases that it sometimes seems I’m watching a flip book show of code.  On top of that, I frequently find myself explaining concepts like the cost of code ownership, and regarding code as, for lack of a better term, inventory.  From the perspective of those paying the bills, maintainable code doesn’t mean “code developers like to work with” but rather “code that minimizes spend for future changes.”

Yes, that money includes developer labor.  But it also includes concerns like deployment effort, defect cycle time, universality of skills required, and plenty more.  Maintainable codebases mean easy, fast, risk-free, and cheap change.  Here are some characteristics in the field that I use when assessing this property.  Some of them may seem a bit off the beaten path.

Read More


What’s in a Name? Spelling Matters in Code

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.

Think back to college (or high school, if applicable).  Do you remember that kid that would sit near the front of the class and gleefully point out that the professor had accidentally omitted an apostrophe when writing notes on the white board?  Didn’t you just love that kid?  Yeah, me neither.

Fate imbues a small percentage of the population with a neurotic need to correct any perceived mistakes made by anyone.  XKCD immortalized this phenomenon with one of its most famous cartoons, that declared, “someone is wrong on the internet.”  For the rest of the population, however, this tendency seems pedantic and, dare I say, unpleasant.  Just let it go, man.  It doesn’t matter that much.

I mention all of this to add context to the remainder of the post.  I work as a consultant and understand the need for diplomacy, tact, and choosing one’s battles.  So, I do not propose something like care with spelling lightly.  But I will propose it, nonetheless.

Now I know what you’re thinking.  How can caring about spelling in code be anything but pedantic?  We’re not talking about something being put together to impress a wide audience, like a newspaper.  In fact, we’re not even talking about prose.  And code contains all sorts of abbreviations and encodings and whatnot.

Nevertheless, it matters.  When English words occur in your code, spelling them right matters.  I’ll use the rest of this post to make my case.

Read More