Kaitlyn Nicole Barger, born at 1:39AM on 06/24/2009 at Healthpark in Fort Myers, FL. a healthy, happy, 8 lbs, 14 ounces.
A sleepy little girl. Check out all that hair!
My first diaper change and swaddle.
Month: June 2009
Why Use CSS (A brief recap)
By now, just about anyone who has worked on web-based development has heard the arguments against tables in HTML design. Although the vast majority of websites in earlier web development were table based, times have changed and most web developers are coming over to the benefits of purely CSS based design.
There are of course many reasons for this change; namely the separation of page structure and visual aesthetics. Software developers, above all others, should appreciate this singular advantage of using CSS based design over tables and fixed graphics within the HTML.
With a CSS based website or web application you gain the advantage of being able to quickly change the entire look of a website by simply changing an external CSS stylesheet (or collection of css stylesheets) and functionality of the webpage should stay in tact since the underlying HTML structure is unchanged. Additionally, there are SEO advantages to using CSS and div’s versus tables and worse, nested tables.
Common CSS Problem-Area: Forms
So now that we briefly recapped the reasons why as well as a few significant advantages of using CSS, let’s discuss a common CSS problem area; forms.
We’ll use a very simple example which incorporates the majority of elements within a form. The following code examples are written in good-old-fashioned HTML instead of ASP.NET and do not contain validation, ID’s, etc. like a production form would have:
The old way of doing this in HTML would look something like this:
<html> <head> <title>A Simple Table Form</title> </head> <body> <h1>A Simple Table Form</h1> <table> <tr> <td>Name</td> <td colspan="5"><input type="text" size="65" /></td> </tr> <tr> <td>Property Address</td> <td colspan="5"><input type="text" size="65" /></td> </tr> <tr> <td>City</td> <td><input type="text" /></td> <td>State</td> <td> <select> <option value="FL">FL</option> </select> </td> <td>Zip</td> <td><input type="text" size="14" /></td> </tr> <tr> <td>Email</td> <td colspan="5"><input type="text" size="65" /></td> </tr> <tr> <td colspan="6">Message</td> </tr> <tr> <td colspan="6"><textarea cols="65" rows="10"></textarea></td> </tr> <tr> <td colspan="6"><input type="button" value="Submit" /></td> </tr> </table> </body> </html>
Let’s take a look at one approach without tables and using CSS styles (the CSS is incorporated into the head of the HTML for demonstration purposes):
<html>
<head>
<title>A Simple Tableless Form</title>
<style>
.form
{
}
.form span
{
float: left;
width: 120px;
clear: both;
}
.form .normal
{
width: 120px;
float: none;
}
.form .short
{
width: 50px;
}
.form input, .form select, .form textarea
{
margin-top: 2px;
margin-bottom: 2px;
}
</style>
</head>
<body>
<div class="form">
<h1>A Simple Tableless Form</h1>
<span>Name</span>
<input type="text" size="65" /><br />
<span>Property Address</span>
<input type="text" size="65" /><br />
<span>City</span>
<input type="text" />
<span class="normal short">State</span>
<select>
<option value="FL">FL</option>
</select>
<span class="normal short">Zip</span>
<input type="text" size="14" /><br />
<span>Email</span>
<input type="text" size="65" /><br />
<span>Message</span><br />
<textarea cols="65" rows="10"></textarea><br />
<input type="button" value="Submit" />
</div>
</body>
</html>
In production, don’t forget to move the CSS to an external file – which is usually cached by the browser after initially being downloaded. This improves download speed and code maintenance.
The key is the form class and styles within the form class. all ‘s are treated special, so they float left and default to a specified width (which can change based on the form). This lines up the input and the input tag’s vertically so the form looks clean. I generally also include a short style for closer width when necessary. The normal style is to allow non-floated spans for laying form elements out horizontally. Finally, I’ve added some additional spacing to form input controls to make the form easier to read.
A Nice Advantage for CSS Forms
To demonstrate one final advantage let’s take the following scenario: you need to be able to hide or show the state and state dropdown from codebehind, a common example when working with ASP.NET. With the CSS version, you can simply wrap the state span and select input with an ASP Panel and turn the visibility on/off. With a table, this would break the table structure if you remove a column, and if not, you are left with a large gap.
I hope this helps in your next HTML form!
Setting Up the Scenario
What .NET developer hasn’t spent countless times writing documentation that quickly becomes outdated with each code revision?
Ok, so you dreaded doing it, but your brand new development project is done and completely documented. It took you twice as long to write all of the documentation for other developers to use but it’s finally done, and it looks great.
Now, fast forward three months… you’ve addressed a steady list of bug reports, new features, and redesign requirements. Everything is closer to production, so timelines were shortened and the pressure to deliver the fixes was on. What does that documentation look like now? How about three years into the project with new features and maintenance?
The point is, in most companies, especially smaller development teams (1?), documentation tends to suffer. What I’ve found as the best way to maintain documentation (for yourself or for others) is to build it directly from the source code using Sandcastle comments and the Sandcastle Help File Builder.
Sandcastle Comments and Visual Studio
If you’re not familiar with Sandcastle comments, they’re extremely easy and integrated directly into Visual Studio already. To begin adding Sandcastle comments first ensure XML documentation is turned on for the project by rightclicking on your project, selecting Properties, clicking the Build tab and checking XML documentation underneath Output. Now position your cursor above any function, method, class, or property and type /// (C#) or ”’ (VB). Visual Studio will automatically generate a comment structure for the code object.
Functions and methods with parameters will generate stubs for details about the parameters. The more descriptive you are with your comments, the better your documentation will be. This is the most important aspect of documentation, completeness.
Autogenerating Documentation
Now that you’re familiar with Sandcastle commments and know how to decorate your entire project, we can move onto the real meat of this post which is autogenerating documentation for yourself and others to use.
You’ll want to begin by downloading two projects from Codeplex to make extraction and formatting of the comments much easier; these are the Sandcastle Project and the Sandcastle Help File Builder.
Once installed, open Sandcastle Help File Builder, and select New Project. Name the project, and once it finishes startup, right click on Documentation Sources, select a Visual Studio Project or Solution. You can set many different options here or simply click Build. Just like that, you’ve created a .CHM help file. Not impressed? Let’s go one step further and create MSDN-style web-based documentation by simply selecting Help1xAndWebsite under the HelpFileFormat dropdown. Point to an output directory and you’ve got your own min-MSDN.
Additional Benefits
One of the great things about documentation in this way is that it ties your documentation closely to your code. As you change code, your documentation can be easily updated because it intuitively describes the code you are currently updating. Another advantage is to change Visual Studio to treat undocumented code as errors/warnings; this forces you to do the extra work of documentation which you may thank yourself later for.
Hopefully this helps documenting your next project. Happy coding!
*Special thanks to Ben Lawrence for first introducing me to this great codeplex project!
Nicholas Barger's Blog 