The DRY Principle

Sometimes closed circles aren’t funny. Just last night I was reading about the DRY (Don’t Repeat Yourself) principle in a book I recently picked up, The Pragmatic Programmer, Chapter 2.  All good programmers with a bit of experience understand the need for a single point of reference for knowledge.  Start sprinkling your code with literals or perform the same calculations in multiple functions and you’re wasting time, effort and making your code a maintenance nightmare.

What I hadn’t thought of though was time spent duplicating documentation of code.  The pragmatic programmer would say, as many agile programmers also assert, that you document your code through the sparse use of comments and by writing clear, easy-to-understand code in the first place.  What this means, and i’d never considered, is that writing a documentation document, a manual explaining your code and libraries, would the count as duplication of documentation.

The moral of this is to use something like NDoc for generating documentation, rather than relying on developers to update their docs. Why? BECAUSE THEY DONT DO IT! Thats why.

I just spent hours trying to figure out how to get this compiled trim addin to work – and it still doesn’t.  First I was looking for the RegAsm.exe file they claimed was in the Trim Binary directory (it was in the .Net director), then I was looking for the external settings tab (doesn’t exist where it is supposed to) and now it still wont work so i’ve likely gone wrong somewhere in those last two steps.

The API support line has tried to be helpful, but have so far been ineffectual and the SDK documentation that shipped with the product is a joke.

Don’t let this happen to your product. Documentation is important.  Documentation lowered the chance of have a grumpy prick like me yelling at you.  Thats always a good thing. (Amount lowered declines as chance approaches zero – the limit graph of grumpy.)

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s