These postings are provided "AS IS" with no warranties, and confers no rights. You assume all risk for your use.
Jonathan RozenblitDeveloper Evangelist
Susan IbachDeveloper Evangelist
In the past few weeks I have talked about some tips on how to survive when you inherit code from someone that has no associated documentation. We looked at how to generate dependency graphs, and how to generate sequence diagrams. But sometimes we do make an effort to document our code. If you are going to spend time documenting code you want to ensure that is time well spent.
One of the problems I ran into on occasion was documentation that was created during coding could not be located by the developers down the road when they were supporting the application. As a result, I am a big believer in including code documentation within the code itself. If the documentation is part of the project and the code, then anyone who has access to the code has access to the documentation. This is why even though they have been around for a while, I love XML comments and wanted to remind you of a few tips to make them as easy as possible to work with.
To add XML comments to your project just go to the beginning of the class or method and put three “/” marks on a line then hit enter (C#) or three ‘ single quotes (VB). When you hit Enter you will get a skeleton for XML comments you can fill in
/// <param name="StudentToAdd"></param>
public string Add(Student StudentToAdd)
The XML skeleton that is generated will be different depending on where you add the XML comments. The skeleton is just a starting point, you can add a number of other elements to your XML documentation as well by just going inside the XML comments and entering a “<” symbol the intellisense will give you a list of elements to choose from as shown in Figure 1
You probably want to sit down at the beginning of a project and decide what elements you want to include for different objects such as classes, methods and properties. After doing this you will want to standardize it for your team by modifying the default skeletons. Well good news, if you are a VB developer you can create a document called VBXMLDoc.xml, for instructions on where to find this file and how to edit it, see the MSDN article Recommended XML Tags for Documentation Comments. If you are a CSharp programmer unfortunately for now we don’t have an equivalent file, but you can create code snippets for the different skeletons.
By the time you are finished entering the comments it can start to take up a fair bit of screen space which can be annoying when you already know your way around the code. You can collapse/expand the comments using the +/- symbols or CTRL+M CTRL+M (if like me, you prefer keyboard shortcuts) as shown in Figure 2.
So now you have comments in your code, which can be accessed by all programmers who are working on the code in the future, but honestly I can just do that with normal comments and I can use Code Snippets to insert skeletons. So why use the XML comments? there are two great reasons to use the XML comments
When you build your project you can generate a file that contains the XML comments. This gives you one document which summarizes all your classes and their members that you can make available to other team members. To generate the documentation you can either specify /doc using the command line compiler or if you are building from within Visual Studio go to Project Properties | Build | Output and select XML Documentation file as shown in Figure 3
You can generate Help files from XML Comments using Sandcastle which is available on CodePlex. Sandcastle will generate Microsoft style help topics by reflecting your assemblies and reading your XML comments. Help files are an often requested by users and can be a tedious task for development teams so why not leverage XML comments to help with documenting your code and generating the help files!
So instead of creating a separate document that contains the documentation for your code, keep it with your code where the next programmer will always be able to find it, and if you are going to take the time to document your code consider getting your comments to do double duty as source information for user help!
Today’s Top 5 is of course related to documenting your code
5 Best Practices for adding comments to code
Visual Studio, so much more than just a code editor
I recently saw a post in a forum entitled “drowning in sea of exams” complaining about how confused they were by the current Microsoft certification process. At first glance, certification can seem that way, but if you break it down it is actually pretty simple and really makes a lot of sense. If you are thinking of getting certified, you need to complete four steps.
In this blog post I’ll explain how to complete Step 1 - Identify your certification goal/exam, more blog posts to follow on steps 2-4.
To determine your certification goal, you have to figure out:
Saying you have an MCTS or an MCITP doesn’t really tell an employer anything. That’s like saying “I took a course”. A course in what? SQL Server? Spanish? Cooking? You need to be specific when you choose your certification goal, do you want an MCTS SQL Server Business Intelligence, or an MCITP Exchange 2010.
Let’s look at each level, and then you can follow the links to see the technology choices and exam requirements for each level.
This is someone who knows how to perform tasks using a specific technology. Someone who knows the commands, the syntax, what properties to set to enable features. If I am a manager looking to hire someone to do my database backups, I know someone with an MCTS Microsoft SQL Server 2008 Implementation and Maintenance will know how to perform a backup or restore a database. If I am looking to hire someone to write reports I would look for someone with an MCTS Microsoft SQL Server 2008 Business Intelligence Development and Maintenance. (FYI – MCTS is kind of like the old MCP certification, but and MCTS is specific to a technology)
Earning an MCTS will require passing 1 or 2 exams. You can see a complete list of the MCTS certifications for each technology and the exams required to earn each one here.
MCITP is the title for infrastructure technologies, MCPD is the title for developer technologies. the MCITP and MCPD certifications are referred to as Professional level certifications. When you earn an MCITP that tells a potential employer that you not only know how to perform specific tasks with the product, but that you can design a solution with the product. You understand the different features and you know how and when to use them. If I am a manager and I want to hire someone to design my virtualization strategy I would look for someone with an MCITP Virtualization Administrator on Windows Server 2008 R2. If I want to be promoted from web developer to web architect, I would work on earning my MCPD Web Developer 4. (FYI an MCITP is similar to the old MCDBA, MCSA, MCSE certifications, MCPD is similar to the old MCSD)
Earning an MCITP will require earning one or more MCTS certifications and then passing 1-3 additional exams. You can see a complete list of the MCITP certifications for each technology and the exams required to pass each here. You can see a complete list of the MCPD certifications for each technology and the exams required to pass each here.
The Masters certification is a major undertaking and shows that you are an expert in the technology. You have deep technical understanding of all aspects of the product. You are a guru! If you want to go out and help large organizations plan their strategy for implementing a technology, or you want to be THE go-to person on a product, you go for your Masters. Earning a Master certification will require completing one or more MCITP certifications and completing a 2-3 week training program and passing a knowledge exam and a qualification lab exam. Suffice to say I know many many people with MCTS, and MCITP certifications, but only a handful with a Masters certification. It is a big investment and effort to earn, but it certainly distinguishes you from others in your field and is really a badge of honour!
You can see a complete list of the MCM certifications for each technology and the requirements here.
You need to choose the level of certification that is suitable for your role and goals. Every level of certification will require earning an MCTS, so that is always a good place to start. If you follow the link to the MCTS certification listing, you can expand any technology to see the MCTS certifications available for that technology. You will also see the exam or exams you need to pass to earn each certification. As I mentioned before most MCTS certifications only require passing one exam. The figure below shows the list of MCTS technologies, and I have expanded the list of certifications for SharePoint and SharePoint Server. If you are an administrator working with SharePoint 2010 you would want to earn the MCTS: Microsoft SharePoint 2010, Configuration by passing exam 70-667. If you are a developer working with SharePoint 2010 you would want to earn the MCTS: SharePoint 2010, Application Development by passing exam 70-573.
So there you have it, I hope that helps you understand and navigate your way through the Microsoft certifications, and helps you understand what exam you need to take to earn that certification. Next blog I’ll give you some tips on how to prepare for that exam! Certification is good for your career and for building your own skills. It’s not as hard as you think so go out there and get certified
This blog is also posted on Susanibach’s blog
There are a lot of different ways to learn a product or feature. You can watch videos, you can read blogs and articles. You can download training kits and developer guides. These work very well when you have a sandbox to play in, somewhere you can try out the features and code shown in the articles and blogs. But what if you don’t have anywhere to try it out? What if trying something out requires having a sample project as a starting point? Kind of hard to see how to complete testing faster using Test Manager without a project to test or Test Manager! Hard to try out software architecture features without Visual Studio Ultimate and an architecture to explore!
Technology to the rescue! With the rise in popularity and capabilities of virtual machines, more and more product groups are providing Hands On Labs inside virtual machines complete with all the software and sample projects to make it easy for you to try out lots of cool features. Case in point, Brian Keller, an evangelist for Visual studio wrote a blog announcing the Visual Studio team has a Virtual Machine with Visual Studio 2010 RTM loaded with sample data and they have even provided a set of manuals you can use to complete a series of different hands on lab experiences.
You may only use Visual Studio to edit and deploy your code, but there is so much more hiding in there!
Ever wondered how Visual Studio can help you with testing? Check out these labs
Interested in how Visual Studio can help you discover the architecture of a project (since we have been talking about how to handle code without documentation)? Check out these labs
Has ITIL arrived at your company and is everyone asking you about your processes and configuration management? Check out these labs.
You can download the labs here. You can even choose between Hyper-V, Virtual PC 2007, or Windows 7 Virtual PC! There is more detail about the virtual machines, the labs and how to use them at Brian Keller’s blog post “Now Available: Visual Studio 2010 RTM Virtual Machine with Sample Data and Hands-on-Labs”.
Todays Top 5
5 Reasons to check out Tech Days Canada 2011 (in person or online)
This blog is also posted on Susan Ibach’s blog
About once every couple of weeks on Reddit, I see a post like this one asking for advice on preparing for an exam. Whether you are preparing for a .NET exam or an Exchange exam, an ITIL or a Cisco exam, there is a simple plan you can follow to get certified and prepare for exams.
In the last blog, “Does Certification Seem Overwhelming?” I talked about how the Microsoft certifications are organized and how you can figure out which certification to earn and which exams you need to pass to earn that certification. That is step one. Now it’s time to look at Step two
Anyone preparing to take an exam expects to spend a certain amount of time studying. The trick is to spend that time studying as effectively as possible. If you are planning to take a .NET exam and you spend a lot of time in your day to day work serializing classes, don’t spend your evening reviewing how to serialize classes! If you are a database administrator, chances are you know how to perform a database backup, so don’t spend hours reading chapters on how to do backups. The trick is to figure out what will be on the exam that you do not already know. Then you can focus your study time on learning new material that you will need to master to pass the exam.
There are two excellent tools you can use to determine what you do not know:
For each Microsoft exam you can view the exam guide on the Microsoft Learning website. Go to the tab marked Skills Measured. This information is a gold mine! This is a bullet point list of the topics that will be covered on the exam, divided into different content areas. Read through the list of topics (print it out if you need to) and make a note of anything listed you do not know or that you think you need to brush up on.
Skills Measured Tips
I know most of us think of practice tests as a tool for studying, but they are also excellent tools for figuring out what you don’t know. If you go to the Preparation Materials tab in the Exam guide you will find links to MeasureUp and SelfTest. Both these companies sell practice tests you can use to gauge your knowledge and prepare for the exam. I will talk more about how to use them as effective Study Tools in the next blog. They are also excellent tools for finding out what you don’t know. Simply launch a practice test complete 40-50 questions and look at the summary score sheet provided at the end of the test. You will see how you scored for each content topic. If you got 5 out of 5 questions right on Security, don’t spend the next two nights studying security. If you got 0 out of 4 questions on high availability, you know that any time spent reading up on that topic will be time well spent. So your scores per content area on the practice test can help you prioritize how to spend your study time.
Practice Test Tip
Today’s Top 5 is of course related to certification
5 Microsoft Certifications that can help you stand out from the crowd
This post is also available on Susan Ibach’s blog
A couple of weeks ago I talked about the challenges of finding up to date documentation and showed you how to generate dependency graphs to help you figure out the structure of your code using Visual Studio 2010 Ultimate Edition.
This week I want to show you another useful feature in Visual Studio 2010 to help you generate documentation from existing code. The dependency graphs are great for big picture analysis, which assemblies are referenced and the classes in each assembly, but what if I need a lower level of detail?
Once again Visual Studio 2010 Ultimate Edition comes to the rescue with the sequence diagram generator. Maybe you’ve been asked to investigate an error message received by a user when they click on a particular button. You can just go into the event handler and generate a sequence diagram to determine the method calls from that event handler. This is much simpler than manually walking through the code class by class, method by method. Simply place the cursor in the code editor window, within the method for which you want to generated a sequence diagram and right click. Choose Generate Sequence Diagram from the context menu as shown in Figure 1.
When you select Generate Sequence Diagram you get a window which allows you to control the level of detail you want to include in the sequence diagram.
Let’s take a quick look at the different options
If I choose OK and generate the sequence diagram with the default values shown in Figure 2, Visual Studio generates the sequence diagram shown in Figure 3.
You can see my event handler instantiates a new Student object, and then calls the Save method of the Student class which instantiates an instance of the StudentData class and calls the Add method. This is a very simple example, but shows how quickly you can outline method calls from the event handler. Generating a sequence diagram does not take very long so you can experiment with different settings to get the right level of information for your needs.
So once again, without using any external tools, we have the ability to generate documentation for our undocumented project! You already have Visual Studio, it is so much more than just a code editor! For just a quick sense of how much more it can do, just take a minute to look at the Visual Studio 2010 feature comparison chart. What features are you using? Testing? Database development? Version Control? Build Automation?
Today’s My 5 is related to documentation
5 ways to make your code more readable