Writing Better SharePoint Code

A checklist for SharePoint developers

It’s no secret that SharePoint has exploded in popularity over the last two years.  The number of SharePoint projects built in that time is astonishing.  Unfortunately, the number of those projects that have failed outright or else run into significant problems, often leading to cost overruns and extended schedules, is far too high. 

In that time, the 2007 release of SharePoint has gotten better – bugs that existed at RTM were fixed and documentation got better.  True, there are still issues, but it is nearly a 100% certainty that those are known issues, so it is exceedingly rare that a bug in the product is anything more than an annoyance and something to work around.  While the 2010 release of SharePoint has added a lot with new features and functionality, let’s face it, it’s still the same product at its core.  The things that make “doing SharePoint” hard remain largely unchanged.  Furthermore, the problems that most projects run into have very little to do with features and functionality.  The problems usually stem from people and process.

While that may be a bitter pill to swallow, the fact is that it is the truth.  Far too many projects fail due to under skilled practitioners and poor processes.  What does this mean?  Simple: We need to get better.

With that in mind, and borrowing heavily from Joel Spolsky’s Joel Test: 12 Steps to Better Code,  I’d like to propose an updated, somewhat SharePoint-specific checklist of items that can help make all of our projects run more smoothly.  Unlike Joel’s test, I’m going to break this out into two parts:

  1. Environment and Management – things that managers can do to help produce better code
  2. Individuals and Teams: things the developers have to do themselves – either on their own or as part of a developer team.

Like Joel’s test, give yourself 1 point for every “Yes” answer, and subtotal by section.  A matrix is provided at the end to help you see how you did.  Note that these questions should be answered with what happens most of the time.  There will always be situations in which you cannot adhere to one tenet or another for perfectly valid reasons.

Environment and Management

1.   Do you provide your developers with the best machines and tools possible?  We’re talking multi-core CPUs, solid state drives, at least 8GB of RAM and multiple monitors, plus a handful of relatively inexpensive software products.  Is it expensive?  Yeah, a little.  Is it cheaper than constantly hiring new developers?  Absolutely.  SharePoint puts a lot of requirements on hardware and skimping here wastes time and money, raises a developer’s frustration level and cuts their production quantity and quality significantly.

2.   Do you provide your developers with a bug database?  Tracking bugs and being able to refer back to them is critical.  Developers have enough to keep in their heads without having to remember every bug that they were told about on their way out the door.  You should have a policy that if it isn’t in the bug database, the developers aren’t responsible for fixing it.  Period.  End of story.  As an absolute minimum, the Fab-40 bug tracking database can be installed and tweaked to meet the bare minimum definition of a bug tracking system.

3.   Do you provide your developers with a robust source control system?  Things happen.  Things happen to code.  You don’t want your highly paid developers siting around twiddling their thumbs while waiting for a backup tape to be retrieved and a copy of their code from last Monday to be restored.  You don’t want them worrying about breaking things if they try to refactor their code to be more efficient.  You want them confident in the knowledge that when things go wrong, they can quickly and easily recover, all by themselves, in minutes.

4.    Do you provide a quiet working environment for developers?  Developers need to keep far too much information in their heads at any given point to have it all come tumbling down because of noise in a cube farm.  Ask any developer worth their salt and they’ll tell you about getting into “The Zone.”  It’s the place where everything is clicking; they are plowing through the code like a machine.  It is during these moments that the vast majority of their best, most productive code happens.  Unfortunately, all it takes to rip them out of the zone is one overly loud salesperson at the other end of the cube farm yakking about their golf game.  The developer is instantly converted from a coding machine to a Twitter-reading, web-surfing bum and it takes them anywhere from 15 minutes to an hour to get back into the zone. 

5.    Do you provide a common room, or war room, for group brainstorming, group design sessions, etc.?  Number 4 notwithstanding, there are points where developers need to work together to hash out a problem or work through a design.  They need a place to do that where they won’t distract others and don’t need to worry about tracking down an available conference room that will almost certainly not have the tools they need – lots of whiteboard space, an internet connection, conference phone and the reference books they will need.  These sessions will get noisy so they need to be away from other folks who will be distracted by the noise.

6.    Do you hire dedicated testers?  Developers make lousy testers.  Period; end of story.  Don’t even try to cut corners here.

7.    Do developers write and read code during the interview / hiring process?  Developers need to be able to read and write code, not just talk about design patterns.  Find out if they can before you bring on that new employee or contractor; not after.

8.    Are developers expected to know at least some SharePoint administration in addition to coding ability?  SharePoint is a bit of a unique product.  You can’t be a good SharePoint developer if you don’t know at least some administration.

9.    Do you invest in training and conferences for your developers?  I won’t go into the typical tirade about training here, just realize that keeping their skills sharp is important for developers.  In some cases, it’s even more important than a small raise.  The real item to cover here is conferences.  SharePoint people tend to be more social, community- and people-oriented than most developers.  We’re passionate about our product and like to meet and interact with other folks who share our passion.  Whether it’s the type of person the product attracts due to its collaborative nature or whether we become this way after working with the product I don’t know.  I just know that it’s an important part of what we do and I have yet to meet a person who attended any of the major SharePoint conferences who didn’t come away more knowledgeable, more passionate and more dedicated to their trade.

10.   Do you actively look to eliminate unnecessary distractions from your developer’s day?  This is really an extension of number 4, but even if developers have offices with doors, they can still be distracted.  Make it a policy to avoid unnecessary distractions.  Other employees (including other developers) should treat a closed office door as a do not disturb sign.  Avoid phone calls – email is far less disruptive.  Only invite developers to meetings that they absolutely must attend – and maybe have just one day/week dedicated to meetings.  Anything you can do to keep developers “in the zone” will pay huge dividends.

Individuals and Teams

1.    Do you log bugs as soon as you find them?  You have enough other things to try and remember without having to worry about every detail on a bug you just found.  Log it and forget about it until it’s time to fix it.  And whatever you do, resist the temptation to jump in and fix it right away, unless it is directly related to the current task you are working on.

2.    Do you review the bug list periodically (at least once/day) and fix bugs before adding new features?  There is some leeway on this depending on your project, the nature and severity of the bug and some other factors, but in general, you should get in the habit of reviewing the bug list first thing every morning and performing some triage.  Find bugs assigned to you that can be fixed easily and quickly and knock them out first – all in less than an hour.  Next, find the critical bugs assigned to you and tackle those.  These may take from several hours to the whole rest of the day.  Nonetheless, get them taken care of as soon as possible.  The longer you wait to resolve bugs, the harder they are and the more time they take to fix.  Only after you’ve tackled your bugs should you look to start adding new functionality.  As Joel points out in his original list, this also makes your schedule (see #3) far more accurate.

3.    Do you have a schedule and a design specification that are kept up to date?  Before you write this off as a waterfall process antiquity, consider than a mock up on a white board can be a sufficient specification and a set of dates on a scrap of paper, a schedule.  It all depends on what your project and your team need at that moment.  The most important thing is that the developer and the team-lead/project manager know what is being worked on and the current expectation for completing it.  Keep them updated as you progress and then get back to coding.  SharePoint itself would be a great place for tracking some of this.

4.    Do you use SPDisposeCheck as part of your build process?  While the tool isn’t perfect, it is as close as we can get right now.  Run it, review the output and get in the habit of reviewing your code with an eye for disposal problems.

5.    Do you run FXCop, Visual Studio Code Analysis or a similar static code analysis tool and Style Cop or similar source code analysis tool?   – during development (i.e not just before deployment)?  At some point, other people are going to need to read your code.  Using these tools can make that infinitely easier.  It is important that you run them during development and fix issues as they are uncovered rather than just running them once at the end because it is too easy to skip in the push for deployment.  Note that Style Cop is a C#-only tool.  If you code in a different language, just skip that part of this question.

6.    Do you add appropriate comments to your code?  The existence of comments can be verified in Visual Studio or using FxCop, but verifying that the comments are appropriate cannot be done by a tool.  Appropriate comments will lean more heavily on why the code is about to do something and not as much on the how.  Some how-type comments should be included to help break out major sections of code but for the most part a developer can quickly understand the how by reading the code.  The other benefit of this is that it reduced the amount of times you need to update comments when you refactor a section of code.

7.    Do you turn off Twitter, instant messaging and Outlook while you program?  If you’ve been provided with a distraction-free environment, the last piece of this is on you.  You need to be writing code, not seeing what your friend had for lunch or chuckling over the latest LOL-Cat escapades on the web.  You need to get in the zone and produce some solid code.  Only when you’ve been in the zone and made some progress should you allow yourself to be distracted.  Once you’ve popped out of the zone anyway, sure, take a few minutes to decompress and see what’s up in the twitterverse, then get back to work.  The best thing about the LOL-Cats is that they will still be there waiting to entertain you when you come out of the zone.

8.    Have you familiarized yourself with the Patterns & Practices guidelines for SharePoint and actively look to implement the P&P guidelines whenever possible?  There is a wealth of information available here to help you become a better SharePoint developer.  True, not all of it will apply in every situation, but some of it will apply most of the time. Read it, learn it, use it whenever you can.  Your code will be better and you will be a better developer for it.

9.    Do you regularly review the ULS logs on your development box for object disposal or other issues?  SharePoint is very good at hiding problems and making them appear not to exist.  Only by reviewing the logs on your development box can you be sure that your code is functioning properly and not hitting some error that SharePoint is kindly masking for you.

10.   Do you approach every new programming task with an eye towards taking advantage of an out of the box feature before writing custom code?  SharePoint provides a wealth of functionality out of the box.  If you can make use of some of it to meet a requirement, it would be horribly negligent to not do so.  While it is true that sometime you can’t use an out of the box feature for one reason or another, that needs to be a conscious, documented decision so everyone knows that it was considered and not just overlooked.  This one item is so important that if you’re not doing it, you fail, even if you do everything else on this list.

11.   Can you completely reset your development environment in less than 5 minutes?  SharePoint applications have a lot of moving parts and drop lots of artifacts in many different places – content database, configuration database, multiple places on the file system, etc.  Often in the course of development and testing, you need to return to a clean slate – one in which you have never deployed your solutions or built out a site hierarchy – in order to ensure that your code is working or recover from a bug that trashed your environment.  Virtual machine snapshots are one possible answer here though they are often too much (reverting to a snapshot will wipe out everything in your environment, not just the SharePoint artifacts).  Another option is a scripted approach – being able to run a single script to tear down and rebuild your environment (including building out necessary site collections, sites, lists, etc.) is often the right solution.  Make sure that you don’t forget to clean up the WSS Root directories as part of your tear-down.

12.   Do you use SharePoint internally as part of your team process (document storage/collaboration, discussions boards, etc.)?  It just makes sense to use the product whenever possible.  Walking the proverbial mile in our end users shoes just makes us better developers.

13.   Do you use automated unit tests whenever possible?  Realizing that this is a somewhat contentious area, it is nonetheless an important one in which to spend some time.  Not all of SharePoint or your custom code will work with automated tests, but find those areas that will work and use automated tests there.  Be on the lookout for ways in which to increase the amount of your application that can be automatically tested.

14.   Do you implement some degree of continuous integration or an automated build process?  While similar to number 11, this is more geared towards being able to quickly refresh your test environment with the latest updates from all developers.  Especially given the popularity of iterative development processes, it is unacceptable to require more than a few minutes of anyone’s time in order to update the test environment.  A fully scripted, single click (or even better, fully-automated) situation would be ideal, but this is likely unrealistic for most environments.  At worst, a few steps and scripts to run that take only a few minutes is likely acceptable.

15.   Do you perform load testing? SharePoint can scale to thousands of users.  Our code needs to scale along with it.  At a minimum, our specification (see #3) should include the number of concurrent users we need to be able to support and we should make sure that our code operates sufficiently well with at least that many concurrent users; a few more would be better.

16.   Do you test against an environment that mimics your production environment prior to passing the solution on to QA?  If not, it isn’t really a valid test.  You can’t reliably say that your code will work in production without testing it in a similar environment.  Most often this is simply a matter of testing in a multi-server farm as this is usually the biggest difference between development environments and production environments.

17.   Do you deploy to the GAC only when you must, and include a CAS policy for all other assemblies?  For 2010, this might be somewhat replaced by a question about sandbox vs. farm solution but in any event the general gist of the question remains – do you deploy to the lowest permissioned space possible?

18.   Do you follow recommended coding practices for interacting with SharePoint (such as those Microsoft has published here) (and here) ?  The guidance is available, we just need to learn it and follow it.  If not, we deserve bad reputation we and our implementations get.  This is a big part of why SharePoint projects run into issues – people not following published guidance – but it is entirely avoidable.

19.   Do you ensure that SharePoint Designer is never used against your production farm environment as part of deploying, building or configuring your SharePoint application?  Related to #14, but for your production environment, requiring any work in SharePoint Designer as part of your deployment is not scriptable or reliably repeatable and takes too long.  Whether or not you choose to use SharePoint Designer against production for other customizations is a totally separate decision from whether you need it as part of your application deployment.  Note that this would apply equally to manual browser configurations as well.

20.   Do you package all custom functionality as Features and deploy them as Solutions?  Just do it.  There are too many benefits and too few drawbacks (none?) to not do it.

 

Here’s the matrix to compare against:

Environment and Management:

10
: Perfection.  You’re likely in the top 5% of places for SharePoint developers to work

8-9: Not bad, but you need to focus on a few areas

7: This is borderline OK.  Depending on which 3 are missing it could be acceptable or unacceptable.  Nevertheless, there is still room for improvement and some of your folks could likely be easily lured away by someone with a better score.

6 or Below: Time to put down that latte and get things straightened out.  Chances are that your good developers (and likely even your not-so-good ones, too) are looking around for some other place to work.  If you think that’s not a problem, have you tried hiring qualified SharePoint developers lately?

So, managers, how did you do?  If all of this seems a little primadonna-ish, you’re right; it is.  But if you are a consulting company or a company that is heavily invested in SharePoint internally, then it’s important to strive for this perfection.  You’ll keep your developers around longer.  In the long run your costs will be lower and your employees and customers happier.  It’s not an overnight change, but it is a worthwhile investment.

Individuals and Teams:

20: Perfection.  Really?  This is darn near impossible.  Don’t change a thing if this is truly where you are, but maybe you’ll want to go back through the list and see if maybe you didn’t stretch things a little bit too much.

18-19: Very good – definitely above average.  Take some time to look into the missing areas and see if you can’t take things up a notch or two. 

16-17: Pretty good.  Some room for improvement.  Make a concerted effort to work on some of the missing areas.  See if you can’t get up to 18 in the next few months.

15: You’re barely making the grade.  Depending on which items are missing this could be either acceptable or unacceptable.   You’ve got some work to do.

14 or Below: Unacceptable.  All the usual excuses of being too busy don’t hold up.  Take the time and improve, it will give you more time, not less.

Developers, your turn; how did you do?  As you can see, it’s not all about management not supporting you and providing all the latest toys.  Most of this falls on our shoulders.  We need to continually strive to perfect our trade.  “Good enough” is not good enough.  One interesting observation is that many developers and development teams have very good habits and processes for “regular” development but for some reason feel that they can set these aside for SharePoint development.  This is not the case.  Those well-established practices may need to be slightly augmented to work in a SharePoint environment, but they should not be completely discarded.

This is by no means a complete scientific assessment, nor should it be used as anything other than a quick tool with which to evaluate yourself, your environment and your processes and identify areas to target for improvement.  Perhaps there is some value in it for assessing potential employers before accepting a job, but as Joel said, don’t use it for life-and death situations.  This is also not something that can be changed overnight.  Trying to go from a 7 to a 17 in one month is just not going to work.  It’s a progression to approach perfection, not a mad dash to the finish line.

Feel free to add your own questions and remove any that do not apply to your situation (but it’s not fair to just remove all of the ones you answered “No” to just because they’re hard – that defeats the whole purpose of the exercise).  The goal isn’t to try to look better than someone else on paper; the goal honest improvement in ourselves and our work. 

If you’d like, feel free to add your score in the comments below.  Be honest… 

David Mann is a trainer with Critical Path Training and a SharePoint MVP. To read his bio, click his name by his photo.

Hide comments

Comments

  • Allowed HTML tags: <em> <strong> <blockquote> <br> <p>

Plain text

  • No HTML tags allowed.
  • Web page addresses and e-mail addresses turn into links automatically.
  • Lines and paragraphs break automatically.
Publish