Welcome to WebmasterWorld Guest from 50.17.5.36

Forum Moderators: not2easy

Message Too Old, No Replies

Your Way Wanted: How do you comment in CSS and Why?

Practical experience and usage of comments within CSS files.

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

Senior Member

WebmasterWorld Senior Member 10+ Year Member

joined:Jan 7, 2003
posts:1230
votes: 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.

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

Senior Member from MY 

WebmasterWorld Senior Member vincevincevince is a WebmasterWorld Top Contributor of All Time 10+ Year Member

joined:Apr 1, 2003
posts:4847
votes: 0


I very rarely use comments... instead I try to use descriptive names for classes etc. so that they make good sense.
2:49 pm on May 18, 2007 (gmt 0)

Senior Member

WebmasterWorld Senior Member 10+ Year Member

joined:Jan 7, 2003
posts:1230
votes: 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?
3:00 pm on May 18, 2007 (gmt 0)

Senior Member

WebmasterWorld Senior Member 10+ Year Member

joined:June 26, 2004
posts:1497
votes: 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.
3:40 pm on May 18, 2007 (gmt 0)

Senior Member

WebmasterWorld Senior Member 10+ Year Member

joined:Jan 7, 2003
posts:1230
votes: 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.

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

Senior Member

WebmasterWorld Senior Member 10+ Year Member

joined:June 26, 2004
posts:1497
votes: 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 :)

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

Senior Member

WebmasterWorld Senior Member 5+ Year Member

joined:Mar 18, 2007
posts:671
votes: 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]

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

Senior Member

WebmasterWorld Senior Member 10+ Year Member

joined:Feb 18, 2003
posts:921
votes: 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.
10:42 pm on May 18, 2007 (gmt 0)

Senior Member from US 

WebmasterWorld Senior Member fotiman is a WebmasterWorld Top Contributor of All Time 10+ Year Member Top Contributors Of The Month

joined:Oct 17, 2005
posts:4966
votes: 10



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]

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

Senior Member

WebmasterWorld Senior Member 10+ Year Member

joined:June 26, 2004
posts:1497
votes: 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.
11:15 pm on May 18, 2007 (gmt 0)

Senior Member

WebmasterWorld Senior Member 10+ Year Member

joined:Feb 18, 2003
posts:921
votes: 0


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

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

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

Senior Member

WebmasterWorld Senior Member 10+ Year Member

joined:Feb 16, 2004
posts:1341
votes: 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 */
/* ===================================== */

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

Senior Member from MY 

WebmasterWorld Senior Member vincevincevince is a WebmasterWorld Top Contributor of All Time 10+ Year Member

joined:Apr 1, 2003
posts:4847
votes: 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.

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

Senior Member from CA 

WebmasterWorld Senior Member 10+ Year Member

joined:Nov 25, 2003
posts:889
votes: 58



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.

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

Senior Member

WebmasterWorld Senior Member 10+ Year Member

joined:Jan 7, 2003
posts:1230
votes: 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)

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

Senior Member

WebmasterWorld Senior Member 10+ Year Member

joined:June 26, 2004
posts:1497
votes: 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.
4:08 pm on May 19, 2007 (gmt 0)

Senior Member

WebmasterWorld Senior Member 10+ Year Member

joined:Feb 4, 2002
posts:1314
votes: 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?

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

Senior Member

WebmasterWorld Senior Member 10+ Year Member

joined:Jan 7, 2003
posts:1230
votes: 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?

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

Senior Member

WebmasterWorld Senior Member 10+ Year Member

joined:June 26, 2004
posts:1497
votes: 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.
7:51 am on May 20, 2007 (gmt 0)

Senior Member

WebmasterWorld Senior Member 10+ Year Member

joined:Jan 7, 2003
posts:1230
votes: 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.