Copy of the text of the bug I filed into eclipse this evening.
It is logged in bugzilla as #108071.
https://bugs.eclipse.org/bugs/show_bug.cgi?id=108071


In the "New Java Files" code template, can't add comments inside the newly created class.


Problem:
Users can't put comments in a Java class template that are to be embedded inside the class (between the class brackets), so every new class starts with the comments in the right place without requiring the user to edit each class by hand after it's generated.

e.g. I want something like this:
public class Blee {
// constants

// member variables

// constructors

// etc...
}

...but I get this:
public class Blee {

}
// constants

// member variables

// constructors

// etc...

..or if I put in my own brackets, I get this:
public class Blee {
}
{
// constants

// member variables

// constructors

// etc...
}

Steps to reproduce:
Open Window->Preferences->Java->Code Style->Code Templates->Code->New Java Files
Edit the "Pattern:" window to include something like this:

${type_declaration}
// comment

..to get the first result above, or this:

${type_declaration}
{
// comment
}

..to get the second result above.

The Pitch
This is a convenience I've been using for 10 years before I used eclipse. You start with the same file template and fill in what you need, so you always know the basic order of items in every class, and don't have to keep typing in the section headers yourself. Having all files organized the same way with section headers is a best practice that many well-respected developers recommend. Here are some references. They all present their schemes for ordering functions within a file or within a class (as the language warrants) and their recommended commenting formats.

J2EE Design and Development - Rod Johnson p.144-5 "Delimit sections of code."
Code Complete - Steve McConnell p.449 "..order the source file carefully."
C Style: Standards and Guildelines - David Straker p.125 "Sort functions by a standard scheme..."

OK, so it's a relatively small thing, but it bugs me enough I'm willing to fix it myself and contribute the change. All I need is somebody to review the change and give me some advice on logistics (e.g. do you need a CVS changelist or can I e-mail source files, what tests should I run/fix up etc...) and to help choose a preferred solution from the alternatives.

Proposed Solution Alternatives:
1.) Create a new template variable that doesn't hard-insert brackets and allows users to insert their own brackets where they choose in their template. This is my preferred solution for a couple of reasons. First, it is an addition, so it doesn't affect the current user behavior by design, and so is safe from causing regressions based on assumptions of current usage. (Of course, I understand it may cause regressions based on implementation, but I pledge to handle those.) Second, it gives the user the ultimate flexibility in controlling exactly what appears after the type declaration before the opening class brackets, what appears between the class brackets, and what appears after the class brackets. It would go something like this:

${type_declaration_no_brackets}
{
// the template class comments...
}

and could accomodate something as bizarre as this:
${type_declaration_no_brackets}
// some squirrelly thing here, perhaps a comment or future metadata tag
{
// the template class comments...
}// some other squirrelly thing, like a tool-specific embedded comment

2.) Change the behavior so the new type wizard detects if the user has inserted brackets in the template, and if so, uses these brackets instead of hard-inserting their own. This saves creating a new template variable, and seems like a sophisticated solution, but has a couple of strange corner cases. These involve things like putting brackets in a comment that is intended to go after the class, like an embedded comment that some tool would want in the code:

${type_declaration}

// xp3911{unintelligible-junk}

The code would have to be smart enough to parse comments and not include brackets in comments in its detection. Generally, this solution isn't as safe as the first because it changes the behavior of the current ${type_declaration} template variable and may violate some oddball user assumption somewhere.

3.) Change the behavior so the new type wizard considers everything below the ${type_declaration} template variable to be embedded in the class rather than below it. This was the first solution I thought of, but I like it the least because it changes the default behavior of the current ${type_declaration} template variable the most severely, and doesn't have the flexibility to accomodate the squirrelly comments the first solution can handle. Blech. Included here just for purposes of discussion.

So whaddya say guys? Will you accept one of these solutions (or a variation as we agree) if I implement it right? Isn't this what the spirit of eclipse is all about?