homepage Welcome to WebmasterWorld Guest from 54.211.235.255
register, free tools, login, search, pro membership, help, library, announcements, recent posts, open posts,
Become a Pro Member
Visit PubCon.com
Home / Forums Index / Code, Content, and Presentation / CSS
Forum Library, Charter, Moderators: not2easy

CSS Forum

    
Your Way Wanted: How do you comment in CSS and Why?
Practical experience and usage of comments within CSS files.
hakre




msg:3343061
 2:12 pm on May 18, 2007 (gmt 0)

Hi folks! Long time no write here in the forums. But from time to time you need to come back to good old webmasterworld.

This is not a specific problem I have. I want more generally start a discussion here about how you use comments in CSS. I do not mean the one you can use for hacking specific browsers but the ones you write in to comment and structure your files. Do you use them at all? Do you structure your file and if yes, how? Please let me know.

 

vincevincevince




msg:3343066
 2:17 pm on May 18, 2007 (gmt 0)

I very rarely use comments... instead I try to use descriptive names for classes etc. so that they make good sense.

hakre




msg:3343103
 2:49 pm on May 18, 2007 (gmt 0)

yeah i know that this is common as well. can you tell me why kind of naming sheme you're using if any or can you give some examples?

Robin_reala




msg:3343108
 3:00 pm on May 18, 2007 (gmt 0)

Most CSS files I write have an explanatory block at the top and 'headings' for each block of code through the file. You never know when someone else is going to have to debug your file.

I also explicitly comment any hack I use with something like /* :hack: fixes x bug in y browsers */. A lot of my code goes into templates so when we drop a browser from our support list it's easy to go through the file searching for and discarding any hacks specific to that browser.

hakre




msg:3343154
 3:40 pm on May 18, 2007 (gmt 0)

hi robin, thanks for sharing your thoughts. do you have a kind of sheme how you write down the name of the browser? or do you think it's more important to only mark a hack as a hack?

additionally i do it quite the same as you describe. and mostly the first part/section i open is the part to reset the elements.

Robin_reala




msg:3343169
 3:54 pm on May 18, 2007 (gmt 0)

Well, I don't do a generic reset :)

I don't have any scheme for naming browsers, no. I think that I'd be worried if there were enough hacks in my stylesheets to warrant one :)

Xapti




msg:3343274
 5:53 pm on May 18, 2007 (gmt 0)

In a situation where I'd actually have to work professionally, I might use comments, especially if someone else had to see the code, or was working with me.

Because that's not the case, I never use comments, unless I'm cutting out code that I want to be saved, but not implemented.

I've never been big on commenting, it's been the same for programming.

[edited by: Xapti at 5:53 pm (utc) on May 18, 2007]

treeline




msg:3343329
 6:54 pm on May 18, 2007 (gmt 0)

I don't comment, I use names that amount to comments. If the point is to turn the text (or whatever) green, then it's class = green. Make the H1 just the right size in the header? class = header A rule to float the site logo into the upper left corner and clear it? class = logoleft and so forth. Nails 2 birds with one stone, and it's easy to read the html code without referring back to the css stylesheet.

Fotiman




msg:3343541
 10:42 pm on May 18, 2007 (gmt 0)


If the point is to turn the text (or whatever) green, then it's class = green.
...
A rule to float the site logo into the upper left corner and clear it? class = logoleft and so forth.

Ah yes... the exact WRONG way to use CSS.

One of the benefits of CSS and separation of presentation and content is that once you define your markup, you can make changes to the presentation by only touching the CSS file. In your example, you're using class names that describe the "presentation" instead of the "content", which is bad. Here's why:

Suppose you do something like this:

<p class="green">Copyright 2007...</p>

Some day, you decide that you want this to be blue instead of green. If you modify the style for green to have blue color, that's going to be confusing. The alternative is to find all of the places in your markup where you've specified class="green" and change it to class="blue". You're losing the benefit of not needing to touch the markup in this case.

A much better approach is to use class names that describe the content. For example:

<p class="copyrightNotice">Copyright 2007...</p>

Then in your CSS, you would have:

.copyrightNotice { color: blue; }

In this case, you only have to change the CSS, and there is no confusion about what the style does.

[edited by: Fotiman at 10:50 pm (utc) on May 18, 2007]

Robin_reala




msg:3343548
 10:47 pm on May 18, 2007 (gmt 0)

To back Fotiman up, this has happened to me many times in my professional career. It's very much best practise if you want to create a maintainable site.

treeline




msg:3343566
 11:15 pm on May 18, 2007 (gmt 0)

Ah yes... the exact WRONG way to use CSS.

I'd hate to do be caught doing something only half wrong.

lexipixel




msg:3343602
 12:55 am on May 19, 2007 (gmt 0)

I usually start out with a comment block like:

/* ============================================ */
/* domainname.css */
/* ============================================ */
/* Last Updated: 01/01/1980 */
/* ============================================ */
/* author: Alfred E. Newman, aen@mad.tld */
/* ============================================ */

Next, I leave myself some notes about colors in a comment block, like:

/* COLORS: */
/* BLACK rgb(0,0,0) #000000 */
/* WHITE rgb(255,255,255) #FFFFFF */
/* DK. GREY rgb(63,63,63) #3F3F3F */
/* MD. GREY rgb(127,127,127) #7F7F7F */
/* LT. GREY rgb(191,191,191) #6F6F6F */

I add comments ahead of sections where multiple classes and selectors are related, like:

/* ===================================== */
/* CSS for buttons in Top Navigation bar */
/* ===================================== */

..and at the end of the file I add one more block:

/* ===================================== */
/* EOF: domainname.css */
/* ===================================== */

vincevincevince




msg:3343624
 1:50 am on May 19, 2007 (gmt 0)

My biggest concern with comments, and this goes for HTML as well, is that they increase load times. The biggest advantage of CSS as a sheet rather than in the style attribute is the load-time saving.

As for naming ... here are some examples:
- DIVs for structure by ID:
-- #container : if one overall container is needed, due to poor support for width etc. on 'body'
-- #navigation : self explainatory
-- #content : main page content
-- #footer : page footer

I then style the main semantic header etc. elements in order to be able to use them well, i.e. H1, H2, H3.

'em' does not need to be used for italic and so I redefine it for any emphasised inline style I need

I then break down the style sheet by DIV:
- For the navigation DIV:
-- #navigation ul : style the unordered list to use for nav
-- #navigation li : style the list items for it
-- #navigation h2 : style the h2 to make it small enough to be a menu heading
- For the content DIV, I tend to use the globally applied styles - this means if the DIVs for some reason are broken or missing, the content still presents reasonably
- For the footer DIV:
-- #footer a : style footer links

Obviously there are many more... but that's the general way I go about it and I've never found it difficult to use without comments.

iamlost




msg:3343645
 2:52 am on May 19, 2007 (gmt 0)


I've never been big on commenting, it's been the same for programming.

Ah, the no-documentation-job-security angle :-)
Think not only of s/he who comes after you but that memory is fickle.
Documentation is a good thing.


My biggest concern with comments, and this goes for HTML as well, is that they increase load times.

Commentary is one difference between reference code and implemented code. Write it (with comments), test it, save copy as reference/backup, strip comments, compact, upload.

My reference code is about as structured as lexipixel but I put my colour (and background-color, etc.) comments repetitively in line where specified rather than in one grouping. I want all information to hand without scrolling.

I agree (because I do those things too) with Robin_reala on hackery comments and Fotiman on naming format.

You need to know who did it, when, and why.
You also need the ability to change things quickly and easily.
You may also want (OK actually only I have such compulsive behaviour) to remember what was changed, when, and why: versioning.

hakre




msg:3343792
 9:48 am on May 19, 2007 (gmt 0)

Well this is all great Feedback, thanks for the discussion so far. I've seen Reference Color-Tables as lexipixel was writing about (thanks for your nice example anyway!). This might help to styleguide a little as well.

I sometimes even put little ascii-paintings inside my code to write down the measurements of the default layout:


* 788
* 20 748 20
* 20 304 444 20

(The stylecodes of this Forum do not properly preserve the Indents I wanted to use in this Example)

And in a more general perspective, what do you think about this type of commenting CSS:


/**
* Bubblesoap Website Stylesheet
*
* Global Screen Stylesheet for the Bubblesoap Website
* with all the Summer 2007 Styles.
*
* @style Summerscape
* @media screen
*
* @version 1.0
* @date 2007-05-05
* @author Carsten Banski
*
* @colordef Red Wine : rgb(178,25,34);
* @colordef Grassgreen : rgb(74,192,75);
*/
...
/**
* Reset
*
* Reset default Browser Rules
*
* @section Reset
* @todo Input Elements missing
*/
... CSS Rules ...
/**
* Layout
*
* Default positioning of the main site elements
*
* @section Layout
*/
... CSS Rules ...
/**
* Min-Height IE Hack
*
* @hack 100% Page Height
* @hackfor IE 5.5 & 6 Win32
*/
... CSS Rules ...

(The stylecodes of this Forum do not properly preserve the Indents I wanted to use in this Example but I think you understand how this should look like)

Robin_reala




msg:3343821
 11:30 am on May 19, 2007 (gmt 0)

It is possible to overdo comments, but when you're working with a team I think it's quite difficult to. Regarding an increased file size, it's pretty trivial to write a preprocessor that strips them out before they go from staging to live, although in the spirit of the web I generally leave them in so that other people can learn from my code.

victor




msg:3343989
 4:08 pm on May 19, 2007 (gmt 0)

My HTML templates and CSS files are heavily commented.

But only on the dev server. When uploaded to live, the comments are automatically stripped out. As is most of the whitespace.

That gives me, behind the scenes, some extensive in-line notes while putting the smallest/fastest files up for serving to the world.

And stops any embarrassing/rude design comments slipping into the public arena.

I'd've thought everyone does that. If you have a CMS (or whatever) that does not strip comments when uploading to a public environment, why not try another one?

hakre




msg:3344194
 8:39 pm on May 19, 2007 (gmt 0)

hi victor, thanks for taking part. can you share some of your more general thoughts and strategies in commenting CSS? I'm interested in the way you're commenting CSS.

@Robin_reala: what do you mean by overdoing comments? was this related to my example? If yes which part do you think is not useable or when does it not make sense in your opinion to use comments in CSS?

Robin_reala




msg:3344290
 12:37 am on May 20, 2007 (gmt 0)

I suppose I think there's a point where the comments stand hindering comprehensibility. But it does take a while to get there. Also depends on how many other people are going to be looking at your code.

hakre




msg:3344467
 7:51 am on May 20, 2007 (gmt 0)

Yeah, as with everything you can overdo that, shure. I just was asking myself what would be a good guideline in CSS commenting and what would be complete nonsense.

Global Options:
 top home search open messages active posts  
 

Home / Forums Index / Code, Content, and Presentation / CSS
rss feed

All trademarks and copyrights held by respective owners. Member comments are owned by the poster.
Home ¦ Free Tools ¦ Terms of Service ¦ Privacy Policy ¦ Report Problem ¦ About ¦ Library ¦ Newsletter
WebmasterWorld is a Developer Shed Community owned by Jim Boykin.
© Webmaster World 1996-2014 all rights reserved