Shared item

4 shares
Improving Code Readability With CSS Styleguides

via Smashing Magazine by Vitaly Friedman & Sven Lennartz on May 02, 2008
Once your latest project is finished, you are very likely to forget the structure of the layout, numerous classes as well as the color scheme you’ve used in the project. In CSS-files sensible structuring can drastically reduce complexity, improve code management and consequently simplify maintainability. However, how can you achieve sensible structuring? Well, there are a number of options. For instance, you can make use of comments — after all, in CSS-code there is always some area for useful hints, notes and, well, comments you can use afterwards, after the project has been deployed.
Indeed, developers come up with quite creative ways to use comments and text formatting to improve code maintainability. Such creative ways are usually combined into CSS styleguides — pieces of CSS-code which are supposed to provide developers with useful insights in the structure of the code and background information related to it.
This article presents 5 coding techniques which can dramatically improve management and simplify maintainability of your code. You can browse through the references listed under the article — they containt further information about how you can achieve a well-organized and well-structured code.
You may also be interested in the articles:
1. Divide and conquer your code
Consider the structure of your layout and identify the most important modules in your CSS-code. In most cases it’s useful to choose the order of CSS-selectors by the order of divisors (div’s) and classes in your layout. Before starting coding, group common elements in separate sections and title each group. For instance, you can select Global Styles (body, paragraphs, lists, etc), Layout, Headings, Text Styles, Navigation, Forms, Comments, Extras.
To clearly separate fragments of code, select appropriate flags or striking comments (the more stars you have, the more striking a heading is). In CSS-file they will serve as a heading for each group. Before applying a preferred flag to your code, make sure you can immediately recognize single blocks when scanning through the code.
However, this approach might not be enough for large projects where a single module can be too huge. In such cases you might need to divide your code in multiple files to maintain overview of single groups of code fragments. In such cases a master stylesheet is used to import groups. This creates some additional server requests, but produces a clean and elegant code which is easy to reuse, understand and maintain. Thus you need to include only the master-file in your documents.
```
/*------------------------------------------------------------------[Master Stylesheet]Project:	Smashing MagazineVersion:	1.1Last change:	05/02/08 [fixed Float bug, vf]Assigned to:	Vitaly Friedman (vf), Sven Lennartz (sl)Primary use:	Magazine-------------------------------------------------------------------*/@import "reset.css";@import "layout.css";@import "colors.css";@import "typography.css";@import "flash.css";/* @import "debugging.css"; */
```
For large projects or large developer’s team it’s also useful to have a brief update log and some additional information about the project — e.g. you can put the information about who is this CSS-file assigned to and what is its primary use (e.g. Smashing Magazine, Smashing Jobs etc.).
Additionally, you can include an additional debugging CSS-code in case you run in problems. Consider using Eric Meyer’s Diagnostic Styling as a debugging stylesheet to test your CSS-code and fix problems.
2. Define a table of contents
To keep an overview of the structure of your code, you might want to consider defining a table of contents in the beginning of your CSS-files. One possibility of integrating a table of contents in your code is to display a tree overview of your layout with IDs and classes used in each branch of the tree. You may want to use some keywords such as header-section or content-group to be able to jump to specific code immediately.
You may also select some important elements you are likely to change frequently after the project is released. These classes and IDs may also appear in your table of contents, so once you’ll need to find them you’ll find them immediately — without scanning your whole code or remembering what class or ID you once used.
```
/*------------------------------------------------------------------[Layout]* body	+ Header / #header	+ Content / #content		- Left column / #leftcolumn		- Right column / #rightcolumn		- Sidebar / #sidebar			- RSS / #rss			- Search / #search			- Boxes / .box			- Sideblog / #sideblog	+ Footer / #footerNavigation	  #navbarAdvertisements	  .adsContent header	  h2——————————————————————-*/
```
…or like this:
```
/*------------------------------------------------------------------[Table of contents]1. Body	2. Header / #header		2.1. Navigation / #navbar	3. Content / #content		3.1. Left column / #leftcolumn		3.2. Right column / #rightcolumn		3.3. Sidebar / #sidebar			3.3.1. RSS / #rss			3.3.2. Search / #search			3.3.3. Boxes / .box			3.3.4. Sideblog / #sideblog			3.3.5. Advertisements / .ads	4. Footer / #footer-------------------------------------------------------------------*/
```
Another approach is to use simple enumeration without indentation. Such an enumeration is easy to scan and easy to read. Hence, once you need to jump to the RSS-section you simply use a search tool to find “8. RSS” in your code. That’s easy, quick and effective.
```
/*------------------------------------------------------------------[Table of contents]1. Body2. Header / #header3. Navigation / #navbar4. Content / #content5. Left column / #leftcolumn6. Right column / #rightcolumn7. Sidebar / #sidebar8. RSS / #rss9. Search / #search10. Boxes / .box11. Sideblog / #sideblog12. Advertisements / .ads13. Footer / #footer-------------------------------------------------------------------*/
```
```
/*------------------------------------------------------------------[8. RSS / #rss]*/#rss { ... }#rss img { ... }
```
Defining a table of contents you make it particularly easier for other people to read and understand your code. For large projects you may also print it out and have it in front of you when reading the code. When working in team, this advantage shouldn’t be underestimated. It can save a lot of time — for you and your colleagues.
3. Define your colors and typography
Since we don’t have CSS constants yet, we need to figure out some way to get a quick reference of “variables” we are using. In web development colors and typography can often be considered as “constants” — fixed values that are used throughout the code multiple times.
As Rachel Andrew states, “one way to get round the lack of constants in CSS is to create some definitions at the top of your CSS file in comments, to define constants. A common use for this is to create a color glossary. This means that you have a quick reference to the colors used in the site to avoid using alternates by mistake and, if you need to change the colors, you have a quick list to go down and do a search and replace.”
```
/*------------------------------------------------------------------# [Color codes]# Dark grey (text): #333333# Dark Blue (headings, links) #000066# Mid Blue (header) #333399# Light blue (top navigation) #CCCCFF# Mid grey: #666666# */
```
Alternatively, you can also describe color codes used in your layout. For a given color, you can display sections of your site which are using this color. Or vice versa — for a given design element you can describe the colors which are used there.
```
/*------------------------------------------------------------------[Color codes]Background:	#ffffff (white)Content:	#1e1e1e (light black)Header h1:	#9caa3b (green)Header h2:	#ee4117 (red)Footer:		#b5cede (dark black)a (standard):	#0040b6 (dark blue)a (visited):	#5999de (light blue)a (active):	#cc0000 (pink)-------------------------------------------------------------------*/
```
The same holds for typography:
```
/*------------------------------------------------------------------[Typography]Body copy:		1.2em/1.6em Verdana, Helvetica, Arial, Geneva, sans-serif;Headers:		2.7em/1.3em Helvetica, Arial, "Lucida Sans Unicode", Verdana, sans-serif;Input, textarea:	1.1em Helvetica, Verdana, Geneva, Arial, sans-serif;Sidebar heading:	1.5em Helvetica, Trebuchet MS, Arial, sans-serif;Notes:	decreasing heading by 0.4em with every subsequent heading level-------------------------------------------------------------------*/
```
4. Order CSS properties
When writing the code, often it’s useful to apply some special formatting to order CSS properties — to make the code more readable, more structured and therefore more intuitive. There is a variety of schemes developers use their projects. Some developers tend to put colors and fonts first or “more important” assignments such as positioning and floats first. Similarly, elements are also often sorted according to the topology of the site and the structure of the layout. This approach can be applied to CSS selectors as well:
```
    body,	h1, h2, h3,	p, ul, li,	form {		border: 0;		margin: 0;		padding: 0;	}
```
Some developers use a more interesting approach and group properties in an alphabetical order. In this context it’s important to mention that alphabetizing CSS properties may lead to some problems in some browsers. You may need to make sure that no changes are produced as a result of your ordering manipulations.
```
body {	background: #fdfdfd;	color: #333;	font-size: 1em;	line-height: 1.4;	margin: 0;	padding: 0;}
```
Whatever grouping format you are using, make sure you define the format you are using and the objective you want to achieve. Your colleagues will thank you for your efforts. And you’ll thank them for sticking to your format.
5. Indentation is your friend!
For better overview of your code you might consider using one-liners for brief fragments of code. This style might produce messy results if you define more than 3 attributes for a given selector. However, used moderately, you can highlight dependencies between all elements of the same class. This technique will dramatically increase the code readability when you have to find a specific element in your CSS code.
```
#main-column { display: inline; float: left; width: 30em; }		#main-column h1 { font-family: Georgia, "Times New Roman", Times, serif; margin-bottom: 20px; }		#main-column p { color: #333; }
```
You remember exactly what you did and can jump back in there and fix it. But what if you made a lot of changes that day, or you just simply can’t remember? Chris Coyier suggests an interesting solution for highlighting recent changes in your CSS-code. Simply indenting new or changed lines in your CSS you can make recent changes in your code more visible. You can as well use some comments keywords (e.g. @new) — you’ll be able to jump to the occurrences of the keyword and undo changes once you’ve found some problems.
```
#sidebar ul li a {     display: block;     background-color: #ccc;          border-bottom: 1px solid #999; /* @new */     margin: 3px 0 3px 0;          padding: 3px; /* @new */}
```
Page structure. Ok, now you can start to design the site structure adding the main sections. If you prepared a “draft” with the site layout it’s very fast. Whichever choice you do in terms of layout (liquid or fixed), I suggest you to define a class .container which set one time only, the width of all element which it contains. In this way, if you want to change the width of the page, you’ll do it for a single CSS element (.container) instead of all elements which it contains (these elements will fit automatically with the new size).
Conclusion
CSS styleguides are helpful if and only if they are used properly. Keep in mind that you should remove every styleguide which doesn’t effectively help you to get a better understanding of the code or achieve a well-structured code. Avoid too many styleguides for too many elements bundled in too many groups. Your goal is to achieve a readable and maintainable code. Stick to it and you’ll save yourself a lot of trouble.
Sources and Resources
continue reading...
Shared by:
blog comments powered by Disqus
0