Why do teams make their jobs so hard?

The more developers I meet, the more I realize that developers continue to make their own lives difficult. They simply accept that the environment they work in (technically) is all that they have. They don’t bother learning more advanced things about it, or even trying to customize it in any way. It’s even worse when an entire team chooses to just use the default environment and everybody is left on their own to do what they want to develop the product. Granted there is something to be said about just getting something out the door, but if you just open up your IDE and get coding without ever customizing it to how *you* code you’ll soon be running into headaches.

I may end up making this a series of posts so I can simply hand this out to future team members so they can understand how their life could be vastly improved. The first tool I’ll dig into is StyleCop.

If your team is doing manual code reviews (like every team does, right?) I strongly hope that the reviews don’t cover things about formatting the code or naming conventions. Make use of a tool that can enforce those rules for you automatically. This is especially important for a team of developers where everybody has different preferred programming languages. As an example, my current team consists of developers who have backgrounds in VB6, Clojure, Ruby, and Java. That alone is a plethora of patterns for how the code should be formatted. Because everybody’s background drives how they format their code going forward you can wind up with a lot of source code commits that are purely reformatting of code so the next developer can understand the code. Why waste the resources when you can have a tool tell the developer they aren’t following the rules of the team prior to even checking in?

There’s a lot of rules that some people that don’t agree with, but I’ve found good reasons for nearly every single rule that comes with StyleCop. One of the key things to do when using StyleCop is not to every change the default settings that are installed on the machine. StyleCop allows you to create a settings file for a folder (and all of its children folders) that override its parent. My general approach is that in the root of every project folder I place the Settings.StyleCop folder that should apply to every single project.

Now, in that base settings file, I typically change the following options:

• Options –> uncheck “Cache StyleCop analysis results”. I’ve yet to hit a project that takes a long time to analyze, so there’s no point in caching results.
• Settings File –> ensure that “Merge with settings file found in parent folders” is the selected option.
• Rules –> C# –> Detailed Settings –> check “Analyze generate files”. This way if you’re doing some sort XAML work, any XAML generate fields will be flagged as part of the naming conventions.
• Rules –> Documentation Rules –> Detailed Settings –> check “Ignore privates”, “Ignore internals” and uncheck “Include fields”. My main reasoning for turning off this level of documentation is that the classes should be very small and concise to adhere to the Single Responsibility Principle. If the class is so massive that you need to document your fields and all the private members, then you really should be having some lengthy conversations in your code review.
• Rules –> Documentations Rules –> Element Documentation –> Check SA1609, SA1610, SA1628, SA1629, and SA 1630. This way you have everything documented (a) for Intellisense, and (b) so anybody can look at the (hopefully up-to-date) documentation and know what to expect when working with the item.
• Depending on the team/project, I uncheck SA1600, SA1601, and SA1602. This way StyleCop doesn’t complain about having to document every public or protected element, but when there’s some level of documentation it must meet the criteria.
• Rules –> Documentation Rules –> File Headers –> Uncheck SA1633, and check SA1639. I don’t believe every file needs to have documentation about the file. The rest of the documentation should describe all of that pretty clearly. But again, if there is any level of documentation in the file header it needs to conform.
• Rules –> Readability Rules –> Regions –> Check SA1124. For the love of a higher deity, please stop using regions. If you need regions, your code is tackling too much.

That’s quite a bit to configure, but seriously makes your code at least consistent. Not only for yourself, but for your team.

Side Note: For those that use StyleCop, you’ll notice that this means that SA1101: PrefixLocalCallsWithThis. Yes, this is intentional because it does improve readability when I’m looking at the code outside of an IDE. Is the line BuildDetails.Name an instance property digging into the Name property, a static property digging in, and static class, or what? By saying this.BuildDetails.Name it is now much more obvious where I need to look for that code.

Make Sure Your Open Source Project Actually Builds!

I suppose this post could apply to any project, but since I like to dig into open source projects quite a bit that’s what I’m focusing on.

How hard is it to bring a new developer into your open source project?  Outside of the core IDE of choice for the language, what else needs to be installed on the developer’s machine in order to get it to build?  If you have to tell them to install a few versions of .NET, Ruby, Python, and then a slew of other tools, why not just put it in a README file at the root of the project instead of relaying that information to every developer who has to ask you directly?  If I can pull the source down from the repository of choice, I should be able to get up and running with the code base without having to spend even an hour trying to figure out how to build the project.  If it’s a .NET application, I would expect to open it up in Visual Studio and press Cntl+Shift+B and have a successful build.  Even better is if there’s a build script and some batch/shell script that will run the build.  That way the developer can find out if the way they’re compiling the code is the same as what’s available as an official release.  There’s been a number of projects that work 99.999% of the way I need it to, but there’s one small feature I need to add or comment out and recompile the rest to fit my need.  If your official releases are strictly Visual Studio builds, then mention it.  Yes that means *gasp* documenting your project.  Heaven forbid.  A little 1-2 line README file that’s not likely to get out of sync of the code isn’t going to kill you.

Even worse is if a 3rd party library needs to be installed for the code to compile correctly.  Include it in the repository if possible (when licensing doesn’t prevent it), or at least have a README or REQUIREMENTS type document that lets me (as a new developer project) know what else I need to install.  Say you’re developing a WPF project, and you’re using a Codeplex project full of controls, then let me know to install it.  Don’t let there be a missing reference in Visual Studio for me to spend extra time figuring out what it’s supposed to be.

All in all, I suppose this really boils down to asking “Can you build your project on another machine in one simple step?” or “Does your project pass #2 on The Joel Test?”  It really shouldn’t be that hard?

The Problem of Developers and the English Language

This is more of a rant on development rather than useful code, but hopefully it helps provoke some thought.  And while I may be targeting the English language in this post, I believe the other languages run into this issue just as much.

The very first post I made on this blog was a quote from the book "1984" about a pared down language because (a) it surprised me that everybody focuses on the Big Brother aspect of the story rather than the redefined communication, (b) an explicit language where each word can only mean one thing makes a lot of sense, and (c) having words that are meant to be a scale (good, better, best) actually having the same initial word in them (good, plusgood, doubleplusgood) is more in line with the Latin roots of the English language.  Think back to when you were first starting to understand all the oddities that make up the English language.  I before E except after C. To pluralize a word, add an S; except if it ends in these letters, then do this instead.  There’s a lot of rules to the language that don’t make  a lot of sense.  Although I’m pretty sure Ph.D. bearing learned people can give me the reasoning, the general answer to why it must be done this way is “Because that’s how it’s always been done”.  Outstanding.  Way to think outside the box.

When you're gathering requirements for a problem, how often do the developers interpret a different meaning than what the end users actually meant?  Like referring to the "home page" of a site as the first page a logged in user sees versus the first page that every user sees.  When the manager is talking about the project, are they talking about the entirety of building the software, the Microsoft Project file, the Visual Studio project file, or some other meaning to them entirely.  It gets even worse when a word is used that has a completely different meaning in another language (which at least one project has run into).  Assuming you're programming only in the English language, you have somewhere in the range of 475,000 to 600,000 words to work with.  Not only that, but more words are added to the collegiate dictionaries every year.  And then there are words that are commonly used that don't even exist in a standard dictionary.  So why must we overload the same words over and over again?  Stop being lazy and calling every application that serves out data or hosts another application a "service".  Give it a unique name.

Microsoft’s been getting taking flack about overly descriptive (but entirely accurate) developer product names.  Sure it’s easier to simply say “Astoria”, “Geneva”, or “Longhorn”, but unless you’ve heard of them before you have no clue what they’re actually for.  Now hearing “ADO.NET Data Services”, “Claims-based Identity Management”, or “Windows Vista”, you actually have some idea what’s being talked about without having to spend a lot of time digging into what the product actually is (albeit, not a much better idea in the case of Geneva…).  Sure we need to account for being able to talk about things abstractly in some cases, but we should be able to categorize whatever we’re talking about in a similar way that biologists categorize plants and animals.  IIS is a type of web server, which is a type of server, which is a type of computer, etc. StructureMap is a type of IoC containter, which is a .NET piece of software, which is a development tool.  Although there’s a lot of overlap when describing software, it seems like there could be an easier way to describe and categorize specific software.

If you really think about it, each and every word only exists because a group of people have agreed on a general meaning for it.  Words like "blog" and "podcast" were created to sum up new trends in technology that had not been defined at the time.  All it takes is for somebody to come up with a word and others to start using it for it to catch on.  In much the same way Scott Hanselman wants to have a word that says “I’m a technical person and know what I’m talking about”, I’m think I’ll start using Newspeak terminology to better describe parts of the software I write. 

And people wonder why politicians aren't considered intellectual...

Okay, I just found found this article on Tech Dirt that's talking about a proposed bill in New York that'd ban people from using an electronic device while crossing the street. Are you kidding me? A couple people kindly remove themselves from the gene pool (without even trying for a Darwin Award) and this is the way to "fix" the problem. Anybody who is backing this bill is saying that people are too stupid to pay attention to their surroundings. While their at it why don't they propose that all cars should have audio distractions removed from them before they can be sold in the US. Even better, anything that can cause a driver to take their eyes off the road (like a billboard) should be illegal. That way there's absolutely NO possible way people can be distracted and cause injury to somebody else with a vehicle.

Seriously people, what is this world coming to? Has common sense really been tossed out the window? I like to think that with the advancing sciences that humanity is getting smarter, but things like this really make me question that...