tl;dr: I’m not completely sure about React.js yet just because it’s such a different approach, but I really appreciate how easy it is to use it in conjunction with other client side tools.

My shop is looking very hard at moving to React.js for new development and I’m scrambling a bit to catch up as I’ve been mostly on the server side for years. Partially as a learning experience, I’ve been using React.js to rebuild the UI for our FubuMVC.Diagnostics package in FubuMVC 2.0 as a single page application. While my usage of React.js on the diagnostics is mostly about read only data displays, I did hit a case where I wanted a “typeahead” type search bar. While a google search will turn up a couple nascent projects to build typeahead type components purely with React.js, none looked to me to be nearly as mature and usable as the existing typeahead.js query plugin*.

Fortunately, it turns out to be very easy to use jquery plugins inside of React classes so I just used typeahead.js as is. For the StructureMap diagnostics, I wanted a search bar that allowed users to search for all the assemblies, namespaces, and types configured in the main application container with typeahead recommendations. Since I was going to want to reuse that search bar on a couple different little screens, I did things the idiomatic way React wants to be used anyway and created the small component shown below:

In the not unlikely chance that the code below is mangled and unreadable, you can find the source code in GitHub here.

var SearchBox = React.createClass({
	componentDidMount: function(){
		var element = this.getDOMNode();
		$(element).typeahead({
		  minLength: 5,
		  highlight: true
		},
		{
		  name: 'structuremap',
		  displayKey: 'value',
		  
		  // Just a little object that implements the necessary 
		  // signature to plug into typeahead.js
		  source: FubuDiagnostics.StructureMapSearch.findMatches,
		  templates: {
			empty: '<div class="empty-message">No matches found</div>',
			suggestion: _.template('<div><p><%= display%> - <small><%= type%></small></p><p><small><%= value%></small></p></div>')
		  }
		});
		
                // Behind the scenes, this is just delegating to Backbone's router
                // to 'navigate' the main pane of the page to a different view
		$(element).on('typeahead:selected', function(jquery, option){
			var url = 'structuremap/search-results/' + option.type + '/' + option.value;
			FubuDiagnostics.navigateTo(url);
		});
	},
	
	componentWillUnmount: function(){
		var element = this.getDOMNode();
		$(element).typeahead('destroy');
	},

	render: function(){
		return (
			<input type="search" name="search" ref="input" 
                          className="form-control typeahead structuremap-search" 
                          placeholder="Search the application container" />
		);
	}
});

There really isn’t that much to the code above, but the salient points are:

• The componentDidMount() method fires just after React.js renders the component, giving me the chance to apply the typeahead jquery plugin to the DOM element.
• In this case the component is a single HTML element, so I could just use the getDOMNode() method to get at the actual HTML DOM element. In more complicated components you can also use the refs collection.
• I cleaned up and deactivated the typeahead plugin in the componentWillUnmount() method whenever React.js is tearing down the component to clean up after myself

To use the component above, I just embedded it into another component as more or less a custom tag in the jsx markup:

var Summary = React.createClass({
	render: function(){
		var items = [];
		
		this.props.assemblies.forEach(function(assem, i){		
			items.push(AssemblySummaryItem(assem));
			
			assem.namespaces.forEach(function(ns){
				items.push(NamespaceSummaryItem(ns));
			});
			
		});
		
		return (
			<div>
                        
                        // This is all you have to do to include it
			<SearchBox />
			
			<hr />
			
			<ul className="list-group">
				{items}
			</ul>
			
			</div>
		);
	}
});

So what do I think of React.js so far?

Um, well, React is interesting. I know that my initial reaction was similar to many others: “you seriously want me to embed HTML markup directly into JavaScript?” Once you get past that, it’s been very easy for straight forward usages of rendering JSON from the server into HTML displays. I won’t make any permanent judgement of React.js until I use it on something with much more complicated user interactions.

To speak to one of React.js’s major design philosophies, I’ve never liked two way model binding in any user interface technology I’ve ever used because I think it so easily obfuscates the behavior of screens and causes unexpected side effects. I’m not completely sure how well the one way data flow thing is going to work out in bigger applications, but I’m at least initially on board with the React.js team’s basic design philosophy.

One thing to consider is that React.js is much more of a library that you’d use as opposed to an all encompassing framework like Angular.js or Ember.js that you have to wrap your application around. The downside of that is that React.js doesn’t really do anything to encourage separation of concerns or help you structure your application beyond the view layer, but the old presentation patterns that came out of older technologies still apply and are still useful if you just treat React.js as the view technology. You’re just on your own to do your own thinking. The upside of React.js being just a library is how easy it is to use it in conjunction with other tools like the entire jquery ecosystem or bits of Backbone.js or even as something within frameworks like Angular or Ember.

I’ve also done a little bit of a proof of concept of using React.js as the view layer in a possible rewrite of the Storyteller UI into a pure web application. That work will probably generate much more interesting blog posts later as it’s going to require much deeper hierarchies of components, a lot more complicated user interaction, and will push us into exploring React.js usage with separated presentation patterns and much more unit testing.

At least in the circles I run in, there’s been a bit of a meme the past couple years that Functional Programming is the one true path to software programming and a corresponding parallel backlash against almost everything to do with OOP. If React.js becomes more popular, I think that it might help start a rediscovery of the better ways to do OOP. Namely a focus on thinking about responsibilities, roles, collaboration patterns, and object composition as a way to structure complicated React.js components instead of the stupid “Class-centric,” inheritance laden, data-centric approach to OOP that’s been so easy for the FP guys to caricature.

* I’m not really working much on the client side, so what do I really know? All the same, I think the backlash against jquery feels like a bit of throwing the baby out with the bathwater. Especially if you’re constraining the DOM manipulation to the purely view layer of your code.

This is a mild rewrite of an old blog post of mine from 2005 that I think is still relevant today. While this was originally about pair programming, I’ve tried to rewrite this to be more about working collaboratively in general. 

My shop is having some constructive internal discussions about our development process and practices. While I don’t think that Pair Programming is likely to be a big part of our daily routine, I think we could still use a bigger dose of collective ownership in our various code base’s and less silo-ing of developers. Since I’m a typical introverted developer who doesn’t handle hours of pair programming and I don’t think my attitude is uncommon at all, we need to look for ways to get the same type of shared understanding that you would get from 100% paired programming.

One of my suggestions is at a minimum to stop assigning coding stories to a single developer. Even if they aren’t pair programming all the time, they can still collaborate on the approach and split tasks so they can code in parallel. On one hand this should increase our team’s shared understanding of the codebase, and on the other hand it’ll definitely help us work discrete stories serially to completion instead of having so many half-done stories laying around at any one time.

“This is the Way We Do It”

My favorite metaphor for software design these days is a fishing tackle box.  I want a place for everything and everything in its place.  When I need a top water lure, I know exactly where to look.  I put data access code here, business logic there, and hook the two things up like this.  When I’m creating new code I want to organize it along a predictable structure that anyone else on the project will instantly recognize.  When other coders are making changes I want them to follow the same basic organization so I can find and understand their code later.

Each application is a little bit different so the application’s design is always going to vary.  In any agile project you should hit an inflection point in the team’s velocity that I think of as the “This is the Way We Do It” moment.  Things become smoother.  There are fewer surprises.  Story estimates become more consistent and accurate.  When any pair starts a new story, they understand the general pattern of the system structure and can make the mechanical implementation with minimal fuss.

You really want to get to this point as soon as you can.  There are two separate issues to address before you can reach this inflection point:

1. Determining the pattern and architecture for the system under development
2. Socializing the design throughout the development team

To the first point, pairing allows you bring to bear the knowledge and experience of everybody on the team to the work at hand.  It’s just not possible for any one developer to understand every technology and design pattern in the world. By having every developer active in the project design, you can often work out a workable approach faster than a solo architect ever could.  On the one project I’ve done with theoretical 100% pairing, we had a couple of developers with a lot of heavy client experience and me with more backend and web development experience.  By pairing together with our disparate knowledge we could rapidly create a workable general design strategy for the system as a whole by bringing a wider skill set to any coding task.

Right now I’m working some with a system that’s being built by two different teams that work in two very different ways with very different levels of understanding of some of the core architecture. That’s really not an ideal situation and it’s causing plenty of grumbling. There’s a couple specific subsystems that generate complaints about their usability. In one case it just needs to be a full redesign, but that really needs to take place with more than one or two people involved. In the other case, the problems might be from the team that didn’t build the subsystem not understanding how it works and why it was built that way — or it might be because the remaining developer who worked on it doesn’t completely understand the problems that the other team is having. Regardless of what the actual problem is, more active collaboration between the teams might help that subsystem be more usable.

If you’re a senior developer or the technical lead, one of your responsibilities is fostering an understanding of the technical direction to the other developers.  Nothing else I’ve ever done as a lead (design sessions, documentation, presentations, “do this,” etc.) beats working shoulder to shoulder with other developers as a mechanism for creating a shared understanding of the project strategy.  By making every developer be involved or at least exposed to the thinking behind the design, they’ll have much more contextual information about the design.

We have a great policy of doing internal brown bag presentations at our development office and it’s giving our guys a lot more experience in presentation skills and opportunities to learn about new tools and techniques along the way. While I’d like to see that continue and I like learning about programming languages we don’t yet use, I also think our teams should probably speak about their own work much more often to try to create better shared understanding of the architectures and code structures that they use every day.

Part of any explanation or knowledge sharing about your system’s architecture, structure, and build processes needs to include a discussion of why you’ve chosen or arrived at that architecture. One unpleasant fact I’ve discovered over and over again is that the more detailed instructions you give to another developer, the worse the code is that comes back to you.  I simply can’t do the thinking for someone else, especially if I’m trying to do all the thinking upfront independently of the feedback you’d naturally get from working through the problem at hand.  If the developer doing the work understands the “why” of your design or instructions, they’ll often do a better job and make improvements as they go — and that’s especially important if you gave out instructions that turn out to be the wrong approach and they should really do something different altogether.

For example, I’ve spent the last couple years learning where some of the more rarely used cooking utensils and gadgets in our kitchen go. Instead of trying to memorize where each thing I find unloading the dishwasher goes, my wife has explained her rationale for how the kitchen is organized and I’m somewhat able to get things put up in the right place now. Organizing code isn’t all that different.

Improving Our Code vs. Defensiveness about My Code

Don’t for one second discount the psychological advantages of pair programming or even just a more collaborative coding process.  Formal or even just peer code reviews can be nasty affairs.  They can often amount to a divide between the prosecution and the accused.  In my admittedly limited experience, they’ve been largely blown off or devolve into meaningless compliance checks with coding style standards.  Even worse is the fact that they are generally used as a gating process just prior to the next stage of the waterfall, eliminating the usefulness because it’s too late to make any kind of big change.

The collective ownership achieved with pair programming can turn this situation on its head.  My peers and I can now start to talk about how to improve our code instead of being defensive or sensitive to criticism about my code.  Since we’ve all got visibility now into the majority of the code, we can have informed conversations about the technical direction overall.  The in depth code review happens in real time, so problems are caught sooner.  Add in the shifting of different coders through different areas of the code and you end up with more eyes on any important piece of code. The ability to be self-critical about existing code, without feeling defensive, helps to continuously improve the system design and code.  I think this is one of the primary ways in which agile development can lead to a better, more pleasant workplace.

I told myself that when I started my new blog that I’d try not to rant as much as I did in the CodeBetter days, but oh well, here we go anyway:

Software is a young profession and judging from the rate of change and improvement over my 16 years as a software developer, we’re still learning a lot of new lessons — or relearning old lessons for ourselves that some other group of developers already learned years ago. The great part about that ever changing landscape is that constantly learning new tools and techniques is so much more fun than my first job as an engineer where I mostly certified piping system designs with the “boiler code” that dated back to the 1800’s. The downside is that I think that developers as a whole are terrifyingly bad at sharing information and debating or reasoning about the merits of various alternatives — especially if we feel threatened by other developers promoting tools or techniques that we don’t yet know or use.

I want to ban these words and phrases from technical discussions

I’m betting that many of you are familiar with Godwin’s Law:

“As an online discussion grows longer, the probability of a comparison involving Nazis or Hitler approaches 1.”

From my perspective, the importance of Godwin’s Law in practice is that conversations effectively lose all usefulness when highly charged words and hyperbolic comparisons start getting tossed around.  Much like George Carlin’s Seven Dirty Words, I’d like to create a new list of words and phrases that should be banned in technical conversations at least until we learn to use them a little more wisely:

• Pragmatic — If you follow me on Twitter you surely know that I despise the word pragmatic as it’s usually wielded as a magical talisman by inarticulate developers the world over to win debates and justify whatever random decision they’ve made to other developers. More on this in the next section.
• Fetish — As in “I don’t get your fetish for static/dynamic typed languages.” What you’re doing is shutting your mind off to the merits of different ideas than you’re own.
• Zealot — see the above.
• Dogmatic — Dogmatic is generally used as a pejorative term, but sometimes it’s not. Some techniques are most effective when they’re applied consistently. Again, I think developers mostly use this word to denigrate or delegitimize the differing opinions of other developers.
• Academic — Denigrating some technique as being more theory than something that’s practical to use. You might be right and my experience in a couple different fields is that there is some real distance between theory and reality, but using the word “academic” to describe a technique you don’t use is a sign of a closed mind. Sample usage: “OWIN is a kernel of a good idea wrapped in a lot of academic masturbation.” I’m admittedly guilty of using this quite frequently in reference to enthusiastic proponents of functional programming.
• “Why don’t/didn’t you just” — I’m bad about using this on other developers. Sample usage: “instead of unraveling the Gordian Knot painstakingly by hand, why didn’t you just cut through it with the sword laying over there that no one told you about?.” The cruel reality of software development is that frequently the simplest solution involving the least work is not the obvious solution.
• “It’s obvious” — My ex-wife absolutely hated it when her professors in college used the phrase “it should be obvious to the most casual observer” when their point wasn’t clear at all. It’s just a way of either putting down your co-workers or using loaded language to win an argument. Contributed by my colleague Matt Smith.
• “Git r’ Done” — Used non-ironically it’s just a cutesy synonym for “being pragmatic.” I should probably ban “git ‘r done” because in my circles it’s code for bad developers that don’t care about any kind of quality as long as the immediate work gets done sorta, kinda on time and mostly “works.”
• “Use the right tool for the job” — This is an empty calories kind of statement and a cliche. I usually interpret this as “I just want to be left alone to use what I already know and I’m not interested in continuing this conversation”
• “We just have to get this out the door” — I think there’s a real tension and a necessary balance between making decisions tactically for immediate problems and thinking strategically for the long term. While being an architect astronaut is a sign that you’re too far into the strategic side of things, using the phrase “we just have to get this out the door” is often an indication that your team might be veering way too far in favor of short sighted tactical decisions while missing opportunities to improve their productivity by making changes in process, tools, or a redesign of a bad subsystem. My fear — and my experience backs this up — is that teams that use this phrase and moreover believe it, have shut off their minds and just started to bang harder and faster on their keyboard. My favorite analogy for this is always the saying “I’m too busy chopping trees to stop and sharpen my axe!“
• Shiny Object — I’m guilty of this one. As in, “you just want to use XYZ because it’s the new shiny object”
• Cargo Cult — All the analogies to cargo cults and teams just going through the motions of doing Agile development were kind of funny a couple years ago, but I think the term “cargo cult” is over used mostly as a way to put down other people at this point. If you’ve been living under a rock and haven’t heard this term, I liked James Shore’s Cargo Cult Agile from back in the day.

If you use any of these words and phrases to another developer, you might have wasted a chance to learn or teach something new.

Good Decision Making, Modeling, and being Pragmatic

Taking the definition from Merriam Webster, being pragmatic is:

dealing with the problems that exist in a specific situation in a reasonable and logical way instead of depending on ideas and theories

I think that developers often conflate being pragmatic with doing things well. Being reasonable and logical sounds like a great way to be successful, but you can be pragmatic until the cows come home and still make bad decisions all day long if you’re using bad information or not accounting for other factors. Making good decisions isn’t so much about being pragmatic, dogmatic or zealous so much as it is about constructing the right mental model that represents more of the important factors that go into the decision.

As I alluded to earlier, my educational and early professional background is engineering. My primary job was often about creating models to accurately simulate the real world in order to validate decisions or optimize designs. Needless to say, the better and more accurate your models are, the better your real results.

I thoroughly enjoyed a special projects class I took my last year of school where we designed thermodynamic systems based on optimizing either cost or capacity. To do the optimization, you had to model the various factors (length of a connecting pipe, depreciation, rate of heat loss, etc.) with equations that could be solved with optimization software to find local minimums or maximums.

Since it’s just math, two teams working on the same project should always arrive at the same designs and decisions, right? Right?

What we found in the course of doing these projects was (unsurprisingly) that:

• The calculated optimal design could be much different if you added or ignored certain factors. Maybe my team accounted for the pressure drop across a mile of pipeline while the other team assumed that it was constant. Maybe the other team made different assumptions than we did.
• The calculated optimal design could also be much different for shorter timeframes than it was for longer timeframes.

To make this concrete in terms of software development, take the decision about whether or not to write unit tests for any given piece of code:

• Writing the extra code to automate unit tests takes more time than just writing the production code. A big point against the unit tests.
• Only end to end or integration tests would be able to definitively determine problems in the code in question. Don’t write the unit test.
• An end to end test would be very expensive to write. Write unit tests for what you can easily unit test.
• Writing automated unit tests might force changes to the way you structure your code — which might be a forcing function in favor of better factored code which is good or additional complexity that you don’t want
• Without unit tests you might not catch problems until later when the problem will be harder to find and fix. A point in favor of unit tests.
• Using a debugger is an inefficient way to solve problems in code and foregoing unit testing increases the risk of long debugging sessions. Writing automated unit tests frequently reduces the amount of time spent using a debugger.
• Automated tests of any kind definitely save time in regression tests. A point in favor of writing the tests in the longer term.
• The existence of automated tests can lead to better reversibility so that you can make changes safely later. A point that might be very important or not at all.

If you base your decision about whether or not to write unit tests on only one of these bullet points and not a combination of many or all of them, your decision making isn’t as likely to optimal in the end. Also, your decision making should probably come to different results on a one week project versus a multi-year project.

Again, making better decisions isn’t just about being “pragmatic,” it’s about creating a mental model that more completely and accurately accounts for the positives and negatives of any given decision and also being cognizant of the timeframe in which you need to optimize. If you make the decision about whether or not  Making decisions pragmatically but with incomplete information or understanding of your problem is still bad.

Going back to the point about being too focused on making incremental deadlines and being too focused on the tactical, I’ve far too frequently seen teams forgo solving some sort of technical debt issue that is slowing them down because they had to make their next iteration. In the very short term, they might be right — but if the time saved over X number of iterations is greater than the time it takes to solve and fix the technical debt issue then you need to stop and fix that damn technical debt problem.

To make that last paragraph more concrete with a real life example from my shop, let’s say that your team is working with a system where each and every new vertical feature requires changes to code in six different git repositories. Would you continue to pound away on new features to maintain your current velocity, or stop for a little bit to combine all the repositories into a single logical repository where it’s much easier to make changes in one place and very likely increase your velocity afterward?

Lullaby Language 

I asked my Twitter followers for more examples of words and phrases we should ban and a large number of replies contained the word “just.”  As in the time a business analyst told me that if we were to use our brand new website application as the front end for a system built by another branch of our company that neither of us had other seen it would “just be some refactoring.”  Using the word “just” is a perfect example of Lullaby Language that we should probably avoid using because it gives us and our listeners a potentially false sense of security.

Another loaded word is “should,” as in “the new build should work” with an unspoken admission that they hadn’t tested the exact scenario in question. I had a very enjoyable co-worker years ago that would react comically to statements like that with “you said ‘should!'” (for my current colleagues, this is the guy that got me started on the finger on the nose gesture you’ve all seen by now).

Other examples from the peanut gallery were:

• “should be a quick fix/change” — putting pressure on you to turn it around quickly with no real forethought about how big it really is
• “this is too simple/small for testing/versioning” — famous last words…
• “The deadline is already set. Can we make it?” — I really enjoyed Jez Humble’s talk at NDC London last year about how we should concentrate more on delivering value instead of just trying to hit deadlines

Non Technical Folks and Estimation

I got a lot of other complaints on Twitter that mostly boiled down to project managers and other non-technical folks setting deadlines, time limits, or estimates for developers. I’m a big believer in the idea that developers should do most of the estimation work — and even then, those estimates should be treated as unproven working theories. The only time I think a project manager can get away with doing estimation is when there’s plenty of historical data for the project on similar stories and the composition of the team is stable.

Like many developers in Austin of my generation, I started my development career at a large captive IT shop that was famous for generating truly awesome horror stories. The very last thing I did there was to help kick off a new project to replace an existing web application that our business wasn’t happy with and we felt would be easier to rewrite than improve (it build dynamic HTML inside of VB6 COM objects hosted in ASP classic). Since that very year I had had my bonus slashed because of how far off my estimate was for a previous project, I was appropriately paranoid about getting it right this time around. To that end, I spent a lot of time using use case points (this was so long ago that RUP was still cool) to both define the scope and a first estimate. Because I’ve told this story so many times, I still remember the basic details of the proposed system:

1. A small new database schema to be what we’d now call the read side model — maybe 2 primary master/detail tables plus the normal contingent of lookup data tables
2. A pretty complicated web screen with a lot of different user interactions, and this was way before things like jQuery or Angular.js
3. About a dozen integration points to legacy systems that we had had trouble with in previous projects

When we finally got a project manager I tried to present my use case’s and estimates to the new project manager but I was basically told “don’t worry about it hon, I’ll make the project schedule.”

The next day I got the email with the new Excel schedule attached. As memory serves me, it was an old fashioned waterfall schedule that roughly went:

• 40 days for logical database design
• 20 days for physical database design
• 10 days for the integration work
• 10 days for the web application

I was apoplectic because it was pretty well exactly opposite of what I came up with in every way and pushed all the technical risk to the very end of the project — but I quit the very next week anyway so it was okay;) The PM wasn’t amused when I drew two boxes and one line on her whiteboard and said “there, the logical database design is done!”