DaedTech

Stories about Software

Feb
26

By

Secrets of Maintainable Codebases

Category: Language Agnostic Tags: , , |

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

Feb
23

By

What’s in a Name? Spelling Matters in Code

Category: Language Agnostic Tags: | 26 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, 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

Feb
21

By

How to Get Coding Standards Right (and Wrong)

Category: Language Agnostic Tags: , | 23 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, download NDepend and give it a try!

Nothing compares with the first week on a new job or team.  You experience an interesting swirl of anticipation, excitement, novelty, nervousness, and probably various other emotions I’m forgetting.  What will your new life be like?  How can you impress your teammates?  Where do you get a cup of coffee around here?

If you write code for a living, you know some specific new job peculiarities.  Do they have a machine with runnable code ready on day one?  Or do you have to go through some protracted onboarding process before you can even look at code?  And speaking of code, does theirs square with elegant use of design patterns and unit testing that they advertised during the interview process?  Or does it look like someone made a Death Star out of bailing wire and glue?

But one of the most pivotal moments (for me, anyway) comes innocuously enough.  It usually happens with an offhand comment from a senior developer or through something mentioned in your orientation packet.  You find yourself directed to the coding standards document.  Oh, boy.

At this point, I start to wonder.  Will I find myself glancing at a one-pager that says, “follow the Microsoft guidelines whenever possible and only include one class per file?”  Or, will I find something far more sinister?  Images of a power-mad architect with a gleam in his eye and a convoluted variable name encoding scheme in his back pocket pop into my head.  Will I therefore spend the next six months waging pitched battles over the placement of underscores?

Ugh, Coding Standards

In this post, believe it or not, I’m going to make the case for coding standards.  But before I do so, I want to make my skepticism very clear.  Accordingly, I want to talk first about how coding standards fail.

Based on personal battle scars and my own experience, I tend to judge coding standard documents as guilty until proven innocent.  I cannot tell you how many groups I have encountered where a coding standard was drafted, “just because.”  In fact, I’ve even written about this in the past.

Read More

Feb
9

By

Logging for Fun: Things You’d Never Thought to Log

Category: Language Agnostic Tags: |

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

I work as a consultant in the software industry.  This work affords me the opportunity to see and interact with many different teams and thus to observe prevailing trends.  Among these teams, the attitude toward logging tends to be one of resigned diligence.

That is, many developers view application logging the way they view flossing their teeth: a necessary, dull maintenance activity that will pay dividends later.  Today, however, I’d like to encourage readers to consider a different side of logging.  In the right context and with the right intent, the activity can do so much more than simply insulate against audits and facilitate troubleshooting.  Logging can, in a sense, offer similar appeal to journaling or generally recording information for posterity.

Logging loosely consists of two components: recording and storing information.  As application developers, we find our thoughts occupied by the recording and how that affects our code.  We consider the storage and retrieval only inasmuch as it later aids our debugging efforts.  But we can expand the storage to include sophisticated aggregation, filtering, and querying techniques.  And in these techniques, we can find new ways to understand subjects that interest us.

To be a bit more concrete, I’m going to offer some examples in this post of worlds that you can open through logging.  But the examples will require you to view logging not as dumping data to some file, but as recording information in a way that you can mine it for meaning.  Obviously not all of us share the same interests.  But these examples may give you ideas for your own interests, even if they do not all appeal to you directly.

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
Newer Posts »