This past weekend, I spent a great deal of time reworking some parts of our data access layer for Agulus that have been problematic in the past, mostly by trying to get rid of places where we are using ExecuteScalar and places where we are are working with DataTables, as both places are very sensitive to changes in the underlying database schema and the errors don’t surface until runtime, which really stinks. I managed to figure out how to get all the metadata I needed to replace this functionality (some things could be easier….) and proceeded to start editing my templates to achieve this goal. As I did so, I started reflecting on how much I’ve learned, mostly the hard way, about how to manage larger sets of T4 templates while keeping things maintainable. I’ve not seen a lot of guidance floating around on how to deal well with this stuff, so here’s a list of a few things I’ve figured out (so far). Most of the guidance below sounds very much like the guidance you’d expect to see when building something using ASP.NET MVC, which if you think about it, makes a lot of sense since both share many similar concerns. None of these are earth-shattering, but people tend to forget that code that generates code should be maintained at the same quality level as code that is actually being shipped.

I’ve been slowly building a new version of this website, to replace wordpress (and its attendant problems and constant updates) with something a little lighter that I control more tightly (I’m not just rolling my own blog engine, but a platform for several other things I have planned). As I’ve done so, I’ve been rethinking a lot of my approaches to software development for personal projects (corporate projects are a different matter and under different constraints). Given the ever-accelerating rate at which frameworks change, especially client-side javascript frameworks, I’ve had to more carefully assess the risk of major breaking changes and attempt to mitigate those as I switch things over. I’m currently building a fairly lightweight blog editor that allows me to create new blogposts using markdown and publish the rendered HTML in the actual blog itself. None of it is rocket science, but there are a lot of little things to think through. Perhaps one of the biggest things I’ve noticed is how different frameworks deal with extensibility versus ease of initial setup. I’m going to use javascript frameworks as an example of the sort of design decisions I’m dealing with, because it often seems to be the worst offender for me, although it’s likely that much of the difficulty I have on occasion will go away once I’m a little closer to a decade of solid javascript usage (I really only started using javascript heavily in the early days of jquery, although I used it under duress all the way back). While I was originally a fan of larger, more comprehensive systems, such as AngularJS because they handled much of the internals of the front end of the application, I’ve since started to move away from such systems precisely because they attempt to handle the internals of so much of the front end all in one place.

I’ve been on a bit of kick lately, rethinking how I build applications, particularly with the aim of reducing complexity. One thing that has been readily apparent (even in the bad old days when we called it service oriented architecture) is how breaking a system into small, discrete pieces that do a single thing well makes it much easier to maintain and reason about code. This approach works really well for scaling, deployment, and for quickly being able to build out a piece of functionality without entangling it with other systems. The model works really well for the way I typically think about code in general these days. Breaking the system into smaller pieces also allows me to optimize my technology choices for the problem I’m trying to solve at a much more granular level, which often makes things simpler (in practice, I still typically stick with just c# code, but the ability to throw node, ruby, or python into the mix can be handy at times).

Object-relational mappers (hereafter called ORMs) are used to provide a way for one to map an object in an object-oriented language to a table or set of tables in a (usually) relational database. On the Microsoft stack, they’ve become so popular as to be nearly ubiquitous. They do have their detractors, including people that have developed their own, such as Rob Conery, who developed TWO ORMs (Massive and Subsonic). That said, they do often make the earlier phases of a project much easier, by allowing developers to abstract away the pain of relational data access. This is frequently helpful in the early phases of a project because developers are moving quickly and breaking things while trying to quickly iterate over a design. That said, I find that the way ORMs are frequently used is often rather unhelpful as a project matures (and possibly rather unhelpful in the early phases as well).

Contract software developers have to deal with a lot of issues, especially if they are honest. There are loads of scam artists out there who can’t code particularly well, but will throw an application together for a client quickly, often disappearing shortly afterward. I’ve cleaned up lots of code from that sort and it’s a headache. This article wasn’t really written for that sort of developer, however, as I believe it’s very easy to accidentally screw a client over, even when one is otherwise trustworthy and honest, simply because you don’t think through all the implications of what you are doing. Here are ten ways I’ve seen developers screw their clients, without intending to do so. This is aimed more at solo developers, although a number of these points could apply to larger companies as well.

It’s pretty common for developers to disagree on the role of comments in source code, sometimes in a rather vehement manner. I think at least part of the problem comes from a fundamental misunderstanding, in that most developers simply don’t explain well what they mean when they talk of well-commented code. I believe there are multiple types of code comments, of varying value in different stages of a project and I also suggest that when disagreements come to pass over comments, it’s largely because developers are using the same word to describe very different things. Here are the types of code comments I commonly see and what purposes they serve well.

I’ve been working on a side project with a good friend and it uses T4 templates fairly heavily for wrapping database code (no, we couldn’t use EF for this when we started – we might look at it again later though) and for building up a nice wrapper for templated email. It worked like a champ, until I decided to do a bit of code cleanup to make it more aesthetically pleasing to myself. I was getting concerned because the code generated by the templates was somewhere north of 20,000 lines, declared well north of 100 separate classes with dozens of interfaces and lots of logic for interacting with the database (and with caching). It was all beautiful, clean, eloquent code (ok, I’m lying, but it wasn’t ugly enough that I hated it) and did its job remarkably well. I heartily recommend the Tangible T4 Text editor plugin for Visual Studio, as it makes a lot of this code work quite smoothly and pretty much never gave me a problem (I had to look up which tool I was using – I promise you I could remember off the top of my head if it broke regularly).