107917 - Template Style

Status: RESOLVED FIXED

(Bugzilla :: bugzilla.org, defect, P2)

Description

[Matthew Tuck [:CodeMachine]]

We need to work out the style guide for templates.  In particular, whether we
indent to make templates look right, or the source code to look right.

Once this is done we need to document it in the hackers' guide.

Comment 1

[Myk Melez [:myk] [@mykmelez]]

Let's do both per Gerv's post in n.p.m.webtools.

news://news.mozilla.org:119/[e-mail]

Comment 2

[Gervase Markham [:gerv]]

Does this need pushing out? Can't we just decide on something?

Gerv

Comment 3

[Matthew Tuck [:CodeMachine]]

Style Rule: Use template comments rather than HTML comments, etc, so the comment
doesn't pass through to the browser and bloat the download.

Comment 4

[Matthew Tuck [:CodeMachine]]

Fixing component ...

Comment 5

[Gervase Markham [:gerv]]

What I said:

"We need to talk about this, because templates are not the same as code.

The problem is that it's good to nest tags using indentation, but there are
often a large number of levels of tags. Here's what I propose:

2-space indent. Embedded code sections on their own line, in line with outer
tags. So:

<fred>
[% IF foo %]
  <bar>
  [% FOREACH x = barney %]
    <tr>
      <td>
        [% x %]
      </td>
    <tr>
  [% END %]
[% END %]
</fred>

I also recommend we turn on PRE_CHOMP in the template initialisation; this
prevents us bloating the resulting HTML with a load of whitespace the client is
just going to ignore. Combining that with the above indenting scheme happens to
produce nicely-formatted resulting source, as well."

Do we need to define anything else? I prefer to stick to an 80-char line length;
we should certainly define _some_ maximum line length. We might want to add
points about using hashes for readability, as Myk recommended for query.cgi.

Lastly, we should be allowed to reset the indentation back to zero, if it gets
too deep, by using two blank lines:

...
                          <foo>
                            <bar>


<baz rel="yaya" href="http://www.a-long-url.com/more-url-text">
  <another-tag />
  <another-tag />
  <tr>
    <td>
      Foo!
    </td>
  </tr>
  <another-tag />
</baz>


                           </bar>
                         </foo>
...

Gerv

Comment 6

[Dave Miller [:justdave]]

The docs should always be up-to-date when we release.  Forgot to exclude
Documentation when I mass-retargetted.

Comment 7

[Matthew Barnson]

I am putting this into the docs as 4-space indent so that there's no disconnect
between Perl coding standards and Template coding standards.

Comment 8

[Dave Miller [:justdave]]

how does that compare to what's already in use?

Comment 9

[Matthew Barnson]

Guess I'll go need to check out the code on this one, not bothering trying to
resolve it right now.

Comment 10

[Gervase Markham [:gerv]]

A 4-space indent is inappropriate, and the disconnect is intentional. Please
read again what I wrote above.

In code, multi-levels of indentation indicates logic problems, and makes you
lean towards a restructuring. Also, lines of code tend to be long.

In HTML, a line can be a single tag, and deep nesting is common. A 4-line indent
would cause a great deal of trouble because most of the important code would
need to be crammed into the last 30 characters of the line it's on!

Also, all my templates (don't know about Myk's, but he backs my views) are 2-space.

Gerv

Comment 11

[Myk Melez [:myk] [@mykmelez]]

As I said in IRC yesterday:

12:47:30 <myk>	i agree with Gerv.  first of all, there is no reason to maintain a
single indentation standard across totally different kinds of documents just so
we can say we have a standard.
12:48:16 <myk>	the number of different kinds of documents should dictate the number of
standards.
12:49:48 <myk>	so there is no conflict at all between the template and Perl code
standards... each one expresses the optimal formatting for those kinds of files
12:51:04 <myk>	second of all, two-space indents work well for HTML files and HTML
templates for the reason already mentioned: there are often numerous levels of
indentation.
12:53:26 <myk>	also, in my personal opinion, two-space indentation strikes the optimal
balance between no indentation and too much indentation, both of which make it
difficult to discern the document's structure
12:56:36 <myk>	it should also be noted that indentation is not the only mechanism by
which the structure of code or markup can be delineated, and we should not treat
it as such
12:57:24 <myk>	syntax highlighting, code tree generation, and other mechanisms can and
should be used in addition to indentation by Bugzilla hackers to help them read
the code


As with Gerv's templates, all mine are two-space indented, and as far as I know
that means all current Bugzilla templates use two-space indentation.

Comment 12

[David D. Kilzer (ddk)]

Document template versioning information:

For HTML-based templates:
<!-- [e-mail] -->

For non-HTML-based (or, all other) templates:
[%# [e-mail] %]

NOTE: This comment MUST appear as the first line of the file!

Comment 13

[Bradley Baetz (:bbaetz)]

major version update -> incompatible change; an old template won't work
minor version update -> compatiable change; an older template may not be able to
take advantage of new features, but what it had still works.

Comment 14

[Dave Miller [:justdave]]

Barnboy changed his email address and opened a new account instead of having the
address changed on his existing one.  Reassigning all docs bugs to his new account.

Comment 15

[Gervase Markham [:gerv]]

MattyT: are you going to put this stuff in the Developers Guide? If so, this bug
is yours, not barnboy's :-)

Gerv

Comment 16

[Gervase Markham [:gerv]]

MattyT: ping?

Gerv

Comment 17

[Matthew Tuck [:CodeMachine]]

Everything is pretty much within the guide except the indentation policy
mentioned on the first line.  I didn't document because I disagreed with it and
hadn't got around to raising the issue.

As far as I know you're the only one who supports it Gerv.

Comment 18

[Gervase Markham [:gerv]]

What exactly about the indentation policy don't you like? Every single template
in Bugzilla (and there are now over 50) that I am aware of conforms to my
suggestions for indentation (2-space etc.) So I'm not alone :-)

Gerv

Comment 19

[Matthew Tuck [:CodeMachine]]

First Line = "... In particular, whether we indent to make templates look right,
or the source code to look right."

That's what I have a problem with.  And no, they aren't all the same style.  A
quick look shows Myk still uses template-looks-right indentation, even though
all my templates are currently on branches I think.

Comment 20

[Gervase Markham [:gerv]]

> > In particular, [we need to consider] whether we indent to make templates 
> > look right, or the source code to look right.
> 
> That's what I have a problem with.

You have a problem with me suggesting we consider that question? :-)

I suggested an indentation scheme which made the templates look nice, and
mentioned in passing that it also produced readable HTML. It doesn't have to be
one or the other; we can have both. But I agree template readability is more
important than HTML readability - and I chose the scheme I did on that basis.

Gerv

Comment 21

[Matthew Tuck [:CodeMachine]]

You must be looking at different templates than me.

Anyway, nothing more is happening here for 2.16.

Comment 22

[Matthew Barnson]

I'm not touching this one with a 10-foot pole :)  Tell me what you want, and
I'll change the Guide if necessary.

Comment 23

[Matthew Barnson]

Changed my mind.  Lumped this into the FAQ section so we can get the bug off the
boards; if someone later decides to relocate this information, by all means feel
free :)

Comment 24

[Gervase Markham [:gerv]]

This should not be in the FAQ section of the Bugzilla Guide; in fact, it should
not be in the Bugzilla Guide at all. We have a perfectly good Developers' Guide,
where developers look for information relating to development. They will not
look in the Bugzilla Guide FAQ for details of how to write templates.

Please reopen this bug until the information is in the right place :-)

Gerv

Comment 25

[Dave Miller [:justdave]]

.

Comment 26

[Dave Miller [:justdave]]

.

Comment 27

[Matthew Barnson]

Hmm... help me out, I'm not seeing a "Developer's Guide" in my CVS checkout of
the source or on the bugzilla.org website.  What am I missing?

Comment 28

[Dave Miller [:justdave]]

it's in the bugzilla.org website.

Try cvs update -dP

Comment 29

[Dave Miller [:justdave]]

This is sitting too long.  Looks from the comments we have here that we already
have a decision.  Someone just needs to put it in place on the website.

Comment 30

[Dave Miller [:justdave]]

*** Bug 120925 has been marked as a duplicate of this bug. ***

Comment 31

[Joel Peshkin]

Unloved bugs targetted for 2.18 but untouched since 9-15-2003 are being
retargeted to 2.20
If you plan to act on one immediately, go ahead and pull it back to 2.18.

Comment 32

[Jeffrey Bacon]

After reading the Developer's Guide at
http://www.bugzilla.org/developerguide.html, it seems that the information this
bug deals with in already in place:

# Indentation - HTML Templates should have a 2-space indent.

Comment 33

[Gervase Markham [:gerv]]

Fair enough :-)

Gerv