For the 1st part of the Keys To Development Team Success series we are going to look at ways to write effective code in a team environment.
For those of us work in a team development environment we have experienced the frustration of giving our designs/code to another member of the team, and getting back something quite different then we submitted. Since the focus of this series is how to contribute to, and or build a successful development team we will look at ways that we can structure our code so that it is easier for others to read, and pick up as they take on their part of the project.
It is my goal not to provide a comprehensive tutorial on how to write clean code, many others have done that, and it is probably a series in itself. The goal with this article is to provide a few simple tips that will help when working in a team environment, as well as provide some solid resources for further learning.
For many of us single line css, our own routines, choice of naming conventions and personal approach to writing and organizing code is a way of life, and we are very comfortable in it. When working as a part of a development team a lot of these comfort-zones can be challenged, but the ability to be flexible not only saves frustration, but also says a lot to those we work for about our ability to be a productive part of a team, which goes along way in the work place. Here are some things that I have learned, tried, and found to be very helpful. I will provide reference links so you can do more research if so inclined.
1) Link / Import your stylesheets, and scripts.
This may seem like simple beginner css/html, but we must remember that everyone on our team my not be well versed in our areas of expertise. The cleaner and more organized our html (and css) files are the easier it is for others to pick them up navigate through the code and execute their project responsibilities.
One of the ways to do this is to keep all styles out of the html in an external style sheet that you link or import to the html file. The same goes for scripts wether we are using jquery, mootools, or some other scripting we should do our best to keep it out of the main html document (there are exceptions… google scripts, flash, and browser detection to name a few).
The main idea is to keep our code very clean, readable, and easy for others to use. When we compartmentalize our different code elements it makes it easier for others to know what to expect, where to find it, and keeps a solid framework for team development from initial development to revisions. For more on this check out Jina bolton’s presentations on Sexy Stylesheets there are some great insights.
2) The Name Game – Responsible Convention Naming
When creating our html and css files it can be easy (for times sake) to cut some corners and name our div id’s and classes very general terms. Initially I can understand this thought process, but I think we do out team members a disservice by taking this simple approach.
If someone were to pick up our work and need to edit it would our naming conventions help them get to the section they need to edit quickly, or would they have to search through our files filtering through general terms to try to find it? As you can see this isn’t very efficient, I am sure that many of you are thinking “that sounds great in principal, but it just isn’t practical.” I agree there are times and environments that don’t lend to this idea, but as much as we can we should make our best effort to help our team by clearly defining “id’s” and “classes”, so that when someone else picks up one of our files to edit, they can easily find the section where the edits need to take place.
Using terms like main, left, right may seem easy and even familiar to us, but can lead to frustration when digging though files looking for content to edit/update. We should try to give our id’s and classes names that describe their purpose and placement on the page.
Andy Clarke put it well when he said.
“ That is why I think that establishing a set of naming conventions makes sense, not because I’m some kind of Maoist revolutionary who thinks that we should all wear the same grey boiler suits, but because it can make life easier for us and our end-users. “
Our team members and end-users should be the driving force behind setting up good practices. I encourage you if you haven’t to check out his site, and especially his writings I have found them very informative, and helpful.
Again for those of us who use css/html on a more advanced scale some of these concepts may seem simple, but we must remember that the focus of this series is to work towards bettering our development team.
3) Use Comments
If we take into consideration the above ideas and build upon them further by implementing a comment system we all but serve up great mark up on a silver platter for our dev teammates.
Working with Mike A (the new kid on the team) we implemented commenting for easy browsing through code, as well as version tracking to help keep track of when revisions happened and who executed them. This allows us to both work on the same style sheet, or html pretty seamlessly, and will without a doubt increase efficiency of our front end development efforts.
This is something that I also picked up from Jina Bolton’s “Creating Sexy Stylesheets” presentation. As you can see a them the idea is to communicate well by the code we write. At times this will cause us to have to take some extra steps, and go beyond what is asked of us, but in the end it will lend to a better end result, not to mention earn the respect of our teammates, which will go a long way. The only way we can see improvement in our development team is if we start with our contribution.
Wrapping Up
These are just a few simple tips that I have picked up along the way. A lot of the concepts and inspiration comes from talks that I have heard and blogs that I have read. There is a wealth of knowledge out there just waiting to be soaked up.
Next up in the series “Lets hear some chatter (bridging communication gaps).”
If you have any input, or tips that you have used, please share them.
I’m presently working on a project in Maine that has caused a couple of headaches. Some tips I would offer: make sure everyone is using compatible development environments/IDEs. Also make sure that everyone understands how version control works before they commit. Make sure they commit often. These two things alone would have saved our team nearly two days worth of work.
Andrew Maier’s last blog post..The UXBooth Reviews Silverback
Nice article Aaron!
In relation to this I’ve been looking at CSSDOC (http://cssdoc.net/) as a standardised way of commenting and structuring CSS files – which I’m hoping will make working on these files easier in a team environment.
Good ideas, but I have to disagree with part of your suggestion for #2.
“We should try to give our id’s and classes names that describe their purpose and placement on the page.”
One of the goals of XHTML and CSS is to remove/encapsulate the presentational information from the structural. Using class names that describe an elements placement goes against that very principle.
If, in the future, you decide to change the layout of a site, you should be able to do so with no or little markup changes, using only CSS. Obviously the class names won’t stop you from doing that, but it can lead to meaningless identifiers and a lack of semantics.
Example: calling your right hand sidebar #rightSideBar. If you move it to the left, for example, or decide it won’t be a “sidebar” but rather a footnote, the id no longer makes sense. So you’re either stuck with meaningless naming conventions, or you have to edit your markup.
If you called it something like #secondaryContent, however, the name would remain meaningful no matter if it’s to the right or the left, or if it changes from a sidebar to a footnote, aside, or any other piece of secondary content.
@Jordan,
Thanks for posting, I do see your point. What I am trying to get at is that when writing your xhtml/css knowing that others are going to have to edit content, and possibly layout down the road, make sure that naming conventions assist them in doing just that. I may have mis-stated what I meant about location. I was trying to promote avoiding general terms, like #main, #sidebar, #right, #left, and promote id’s that reflect what the content is.
If I am designing something on my own, knowing that no one else will edit, or need to dive into the code, then I agree with most of what you are saying, but when working in a team environment things change a bit, I have to ensure that when I pass along my xhtml/css that the developers are getting it in a way that minimizes guess work for them. Each situation/ project will be different and will allow for flexibility in our approach, and though we have set ideas of how things should be… ultimately what is best for the team, whatever helps my developers, and others who will work on my files is the best approach (granted that it doesn’t break good practice, standards, accessibility etc…).
I am stoked that you posted valuable feedback! Thanks! that is why the blog is here to get people talking and learning from one another.
~ Aaron I
@admin
I totally agree with doing whatever you can to make working in a team easier. God knows I’ve had my fair share of mishaps with my team regarding naming conventions.
But I don’t think the two are necessarily mutually exclusive.
” I was trying to promote avoiding general terms, like #main, #sidebar, #right, #left, and promote id’s that reflect what the content is.”
Ah, then that makes a world of difference, and I guess I misread your post
Looks like we ended up saying pretty much the same thing.
Cheers.
@Jordan,
haha I don’t think you misread… I most likely mis-typed
Great point!
Thanks again for interacting.
~ Aaron I
Working with multiple people on code isn’t an easy task. Everyone has their own style, and their own way of doing things. The most important parts that I gathered is definitely communicating what goes where and what does what. Haha! I usually split up my style sheets into 3 parts (master.css for the skeleton, ie.css for cross browser changes, then sometimes color.css or spec.css for modular parts), this way if someone needs to focus on making a change, if they do make a mistake they won’t effect the entire scope, and it will be easier for them to catch up on only one part instead of one long master style sheet. Nice topic, great write up!
@patrick,
Great feedback, and good insight into multiple style sheets.
Thanks for commenting
~ Aaron I
I don’ think that these are great ideas for a team. I think that these are great ideas for EVERYONE. The fact is that even if you are a solo developer, most of the time at least one other person is going to work on your project at one point.
The more people that follow a given practice, the better.
The problem with linking/importing stylesheets from one another is you are essentially tightly coupling them. What if I didn’t want one of the stylesheets on a given page? Too bad. What you could do is write a PHP class to include your stylesheets. That way you could call your sheets like this href=”styles.php?load=home,fonts,tables,reset”. Not only will this give you some flexibility, but you could also perform some gzip compression and have them load a lot quicker.
Brandon Hansen’s last blog post..Google Cache: Is it Needed Anymore?
@brandon
Thanks for taking the time to comment, and thanks for the php tip sounds very efficient and useful!
Thanks for visiting the site look forward to your feedback as this series (and future series as well) unfolds.
~ Aaron I
I have really been digging the stylesheets that come with the 960 grid system. @NathanSmith divided them up in to three main stylesheets:
1. core 960.css (I use it if I’m using the grid system)
2. reset.css (a good assortment of resets to start off any project)
3. text.css (a great way to separate your font styles from the structure of your webpages)
I’ve also really become a fan of commenting out my html as well as css files. Not only does it give me a better understanding of the code when I revisit it months later, but it also helps others out on our team when they have to look at the code. And since we use a team in India this plays a very crucial role.
Thanks Aaron for being such a valuable part of the design/development community and posting topics like this. Not only is itself filled with great information, but it allows for a conversation from other professionals to build upon it.
-peace-
kyle steed’s last blog post..in the eternal mind
@Kyle
Great input man, we have an offshore team as well, so commenting plays a big part in what we do.
Thanks for commenting man…
~Aaron I
I’ve never worked in a group environment so I don’t have much insight into that. But I always comment my HTML and CSS so that everything is very clear in case another developer takes over the maintenance of the site in the future.
Perhaps if the team established their own standard of doing things, such as developing a CSS framework they would always start from and using the same type of id’s and classes in each design. That way everyone would become familiar with the way everything is coded and there would be less confusion. Probably would speed up development time as well.
These are really useful. They also apply not just to web and coding work, but to many design projects in general. I only wish my predecessor had followed these!
Sarah’s last blog post..Fabulous Paper Art