6 Tips to Improve Code Downloads for your Blog

Don't you just hate it? You read an interesting programming related article on the web that comes with source code. You downloaded the source so you can look at it later. When you open the file later, you've long forgotten where you got the file, or which concept it was supposed to demonstrate. Worse, the download contains a gazillion files, making it pretty impossible to find the stuff you're looking for yourself. Rather than two or three files demonstrating the topics originally discussed in the article you read, you're faced with a gazillion ReSharper cache files, useless .suo and .user files, obj folder and more. Take, for example, this article "Using Dynamic Views In ASP.NET MVC 2" (note: I am not picking on the author here personally; it's just an example I ran into recently that shows most of the problems I face with code downloads; it's easy to come up with many other examples). The relevant code is only 18 lines long (7 in the View and another 11 in a controller class), yet when you unpack the zip file you get 79 files. Granted, some are needed to run the example as an MVC site, but with a bit of clean up, the number of files can easily be reduced to 27 plus 1 by following these simple tips.

Clean Up Your Code Before You Post

  1. Delete cache files from Resharper, CodeRush or any other useful plugin used in Visual Studio. There's a fair chance your reader is not using one of these plugins, or at least not the one you are using. I use CodeRush from DevExpress, so I don't need your gazillion ReSharper cache files, thank you.

  2. Remove Visual Studio user files, such as .suo and .user files. Most of the times, these only make sense on the machine that created them.

  3. Delete build artifacts. Unless you want to distribute your example as a runnable demo, you typically don't need to include the assemblies that result from your project. They'll be created automatically when the user recompiles. Same goes for the XML documentation files and the pdb files. Delete the obj folder as well because it gets created when you recompile.

  4. Clean up the project. For example, when you're releasing an MVC application that shows something in the Home controller, delete the Account controller and Views folder. This makes it easier for your reader to find what they are looking for.

  5. If possible, clean up web.config by removing references and configuration not needed for the article. It minimizes the chances the application doesn't compile on the reader's machine.

  6. Include a Readme file that describes where the source comes from and preferably, how to get in touch with the author. In most of the downloads on my site, I include a Readme file like this one:
This sample code is a supplemental download for the article:

"Changing the Login Control to Display a List of Users"

You can view the original article here: 

http://imar.spaanjaars.com/409/changing-the-login-control-to-display-a-list-of-users

If you have questions or comments about the article or code download, 
use the Contact page on my web site or the Talk Back feature at 
the bottom of the article on my web site.

Have fun,

Imar Spaanjaars

http://imar.spaanjaars.com

Note: I am guilty of not following the last rule for all my content I've published on my web site consistently, but I am updating downloads while writing this article. Let me know if you find one without a readme.

By following these steps, you'll make it easier for your reader to work with the code you're supplying.


Where to Next?

Wonder where to go next? You can post a comment on this article. You can read existing comments below or you can post a comment yourself on this article .


Consider making a donation
Please consider making a donation using PayPal. Your donation helps me to pay the bills so I can keep running Imar.Spaanjaars.Com, providing fresh content as often as possible.



Talk Back! Comment on Imar.Spaanjaars.Com

I am interested in what you have to say about this article. Feel free to post any comments, remarks or questions you may have about this article. The Talk Back feature is not meant for technical questions that are not directly related to this article. So, a post like "Hey, can you tell me how I can upload files to a MySQL database in PHP?" is likely to be removed. Also spam and unrealistic job offers will be deleted immediately.

When you post a comment, you have to provide your name and the comment. Your e-mail address is optional and you only need to provide it if you want me to contact you. It will not be displayed along with your comment. I got sick and tired of the comment spam I was receiving, so I have protected this page with a simple calculation exercise. This means that if you want to leave a comment, you'll need to complete the calculation before you hit the Post Comment button.

If you want to object to a comment made by another visitor, be sure to contact me and I'll look into it ASAP. Don't forget to mention the page link, or the QuickDocId of the document.

For more information about the Talk Back feature, check out this news item.



 
QuickDocId 548
Full URL http://imar.spaanjaars.com/548/6-tips-to-improve-code-downloads-for-your-blog
Short cut http://imar.spaanjaars.com/548/
Written by Imar Spaanjaars
Date Posted 07/01/2010 15:45