From #998526: Simplify stylesheet organization using SMACSS categories:

All that documentation is extremely useful, but it's too much text for a tpl file. In most cases the comments are way longer than the code. I feel like I'm constantly deleting them just so I can see my code without having to page down. Once I delete them I feel like I can breathe, and ironically my template file feels easier to understand. But I never feel good about deleting documentation, or having to dig up a pristine copy of e.g., page.tpl.php just to see a list of variables.

The placement of lengthy documentation inside the tpl file contributes to Zen's reputation for being bloated. It is common to see people brag about their solution using "less code than zen’s opening page.tpl.php comment".

It isn't fair to penalize Zen for having good documentation, but the location of the documentation does cause unnecessary friction in my daily workflow. Good documentation shouldn't be a penalizing factor. Especially when, as before, we can have our cake and eat it too. Just move all the non-critical documentation to the and replace it with a URL.

An extreme example of cutting every non-essential line in page.tpl.php:

 * Complete documentation for this file is available online:
 * @see

(Where the URL would link directly to the page documenting that specific template.)

I realize this suggestion exceeds the scope of the original topic of stylesheets, but the idea is the same: Improve the experience for the themer by reducing unnecessary bloat and reducing friction wherever possible without sacrificing any valuable documentation.


JohnAlbin’s picture

Status: Fixed » Closed (fixed)

Automatically closed -- issue fixed for 2 weeks with no activity.

Anonymous’s picture

Issue summary: View changes

Add proper link