Yep, but I'm still waiting for my account...
On Sep 30, 2010 4:52 PM, "Kalle Korhonen" <[email protected]>
wrote:
> Fixed. Faster to fix yourself than send an email, no?
>
> Kalle
>
>
> On Thu, Sep 30, 2010 at 3:31 PM, Josh Canfield <[email protected]>
wrote:
>> typo in Copyright section: "try to check the coyright date"
>>
>> On Thu, Sep 30, 2010 at 2:49 PM, <[email protected]> wrote:
>>
>>> Developer Bible<
https://cwiki.apache.org/confluence/display/TAPESTRY/Developer+Bible> Page
>>> *added* by Howard M. Lewis Ship<
https://cwiki.apache.org/confluence/display/~hlship>
>>>
>>> This is a semi-random outpouring of thoughts related to being a Tapestry
>>> committer.
>>> IDE IntelliJ
>>>
>>> It's a free license for all committers and it's just better. Yes, the
first
>>> few days
>>> can be an unpleasant fumble because everything is almost, but not quite,
>>> familiar. Pretty soon you'll love IDEA and
>>> recognize that Eclipse has been bending you over and doing unspeakable
>>> things.
>>>
>>> There are shared code formatting settings in
*<support/idea-settings.jar*>.
>>> This will prevent
>>> unexpected conflicts due to formatting.
>>> Eclipse
>>>
>>> Howard uses this ... because he can't manage to switch IDEs constantly
(he
>>> uses Eclipse for training). Lately
>>> its gotten better.
>>> Copyrights
>>>
>>> All source files should have a copyright comment on top, except where
such
>>> a comment
>>> would interfere with its behavior. For example, component template files
>>> omit the comment.
>>>
>>> The year on the copyright should be updated as a file changes. As you
are
>>> reviewing your changes
>>> before checking them in, try to check the coyright date, and add the
>>> current year to the list if not
>>> present.
>>> Commit Messages
>>>
>>> Always provide a commit message. I generally try to work off the JIRA,
so
>>> my commit message is often:
>>>
>>> TAP5-1234: Make the Foo Widget more Ajax-tastic!
>>>
>>> It is *very important* to include the JIRA issue id in the commit. This
is
>>> used in many places:
>>> JIRA links issues to the SVN commits for that issue (very handy for
seeing
>>> what changed
>>> as part of a bug fix). The Hudson CI server does as well, and will
actually
>>> link SVN commits to issues after
>>> succesfully building.
>>> JIRA Procedures
>>>
>>> All Tapestry committers should be registerred with JIRA and part of the
>>> tapestry-developers JIRA group.
>>>
>>> I work the following JIRA list: JIRA Work Queue<
https://issues.apache.org/jira/secure/IssueNavigator.jspa?mode=hide&requestId=12311597
>
>>> .
>>>
>>> Ideally, we would always work top priortity to low priority. I (Howard)
>>> sometimes jump out of order,
>>> if there's something cool to work on that fits in an available time
slot.
>>> Alternately, you are always
>>> allowed to change the priority of a bug before or as you work it.
>>> Starting work
>>>
>>> When you start to work on an issue, make sure it is *assigned to you*
and
>>> use the *start progress*
>>> option.
>>>
>>> I often add comments about the state of the fix, or the challenges in
>>> creating a fix. This often spurs the Issue's adder to
>>> provide more details.
>>>
>>> I often update the issue description to make it more legible and more
>>> precise, i.e., "NPE in CheckUpdates"
>>> might become "NullPointerException when checking for updates to files
that
>>> have been deleted". Verbose is good.
>>> Closing bugs
>>>
>>> Is it a bug fix without tests? *No.* In some cases, I write new tests to
>>> prove that an issue is not valid and
>>> then leave the tests in place – then close the bug as invalid.
>>>
>>> A good plan is to write a test that fails then work the code until the
test
>>> passes.
>>> I'm also surprised by how often code works in a unit test but fails
>>> unexpectedly in an integration test.
>>> As the G-Man says *"Expect unforseen consequences"*.
>>>
>>> When you check in a fix, you should *close* the issue and make sure the
*fix
>>> release* is correct.
>>>
>>> We're playing fast and loose – a better procedure would be to mark the
bug
>>> resolved and verify
>>> the fix before closing it. That's ok, we have a community to double
check
>>> our work .
>>>
>>> For anything non-trivial, wait for the Hudson CI server to build. It
>>> catches a lot of things ... such as
>>> files that were not added to SVN. And even IntelliJ has a bit of trouble
>>> with wildly refactored code.
>>> Hudson will catch all that.
>>> Invalid issues and duplicates
>>>
>>> Always provide comments about why_ an issue is invalid (*"A Ruby
>>> implementation of Tapestry is out of scope for the project."*), or at
>>> least, a link to the duplicate issues.
>>>
>>> Close the issue but *make sure the fix release is blank*. Otherwise, the
>>> issue _will be listed
>>> in the release notes_, which we don't want.
>>> Copyrights
>>>
>>> The ASF copyright must appear on all Java source files. Technically it
>>> should appear on all non-binary
>>> files in the repository.
>>>
>>> As you make changes to files, update the copyright to add the current
year
>>> to the list. The goal is that the copyright
>>> notice includes the year in which files change. When creating a new
file,
>>> don't back date the copyright year ... starwith the current year. Try
not to
>>> change the copyright year on files that haven't actually changed.
>>>
>>> IntelliJ has a great comparison view: Cmd-9 to see the local changes,
the
>>> Cmd-D to see the differences.
>>> I whip through the changes (using Cmd-forward arrow) and make sure
>>> copyrights are up to date as I review the changes
>>> prior to a commit.
>>> Public vs. Private/Internal
>>>
>>> This is a real big deal. As long as code is in the internal package, we
>>> have a high degree of carte-blanche
>>> to change it. As soon as code is public, we become handcuffed to
backwards
>>> compatibility.
>>>
>>> *Interfaces are public, implementations are private*. You can see this
is
>>> the bulk of the code, where
>>> org.apache.tapestry5.services is almost all interfaces and the
>>> implementations are
>>> in org.apache.tapestry5.internal.services.
>>>
>>> Many more services have both the interface and the implementation in
>>> org.apache.tapestry5.internal.services.
>>>
>>> We absolutely *do not* want to make Page or ComponentPageElement public.
>>> You will often see
>>> public service facades that take a page name as a method parameter,
>>> and convert it to a page instance before invoking methods
>>> on internal services.
>>> Evolving Components
>>>
>>> We do not have a specific plan for this yet. Future Tapestry 5 will add
>>> features to allow clean renames
>>> of parameters, and a way to deprecated and eventually remove components.
>>> Evolving Interfaces
>>>
>>> Tapestry uses interfaces quite extensively.
>>>
>>> Interfaces fall into two categories: service interfaces called by user
>>> code, and interfaces implemented by user code.
>>>
>>> Internal interfaces may be changed at any time. That's why so much is
kept
>>> internal.
>>> Service Interfaces
>>>
>>> New methods may be added if absolutely necessary, but this should be
>>> avoided if at all possible. Don't forget
>>> the @since Javadoc annotation.
>>>
>>> Consider having a stable public facade service whose implementation
calls
>>> into one or more internal service.
>>> User Interfaces
>>>
>>> These should be frozen, no changes once released. Failure to do so
causes
>>> *non-backwards compatible upgrade problems*;
>>> that is, classes that implement the (old) interface are suddenly
invalid,
>>> missing methods from the (new) interface.
>>>
>>> Consider introducing a new interface that extends the old one and adds
new
>>> methods. Make sure you support both.
>>>
>>> You can see this with ServiceDef and ServiceDef2 (which extends
>>> ServiceDef). Yes this can be a bit ugly.
>>>
>>> I actually have utility methods that convert from ServiceDef to
>>> ServiceDef2, adding a wrapper implementation around
>>> a ServiceDef instance if necessary:
>>> Use of @since
>>>
>>> When adding new classes or interface, or adding new methods to existing
>>> types, add an @since Javadoc comment.
>>>
>>> Use the complete version number of the release in which the type or
method
>>> was added: i.e., *...@since 5.1.0.3*.
>>> Code Style
>>>
>>> Yes, at one time I (Howard) used leading underscores for field names.
I've
>>> since changed my mind, but
>>> I unfortunately infected other people; please try to make your code
blend
>>> in when modifying existing source.
>>>
>>> Long ago, Tapestry (3) code used the regrettable
"leading-I-on-interfaces"
>>> style. Don't do that. Everything's an interface.
>>>
>>> I prefer braces on a new line (and thus, open braces lined up with close
>>> braces), so that's what the default
>>> code formatting is set up for. I sometimes omit braces for trivial if
>>> statements, such as {{ if (!test) return; }}.
>>>
>>> I use a lot of vertical whitespace to break methods into logical
sections.
>>>
>>> We're coding Java, not Pascal; I'd much rather see a few checks early on
>>> with quick returns or exceptions than
>>> have ten-levels deep block nesting just so a method can have a single
>>> return statement. In other words,
>>> *else considered harmful*. Low code complexity is better, more readable,
>>> more maintainable code.
>>>
>>> I don't bother alphabetizing things, because I have an IDE that lets me
>>> jump around easily.
>>>
>>> *Final is the new private.* Final fields are great for multi-threaded
>>> code. Especially when creating
>>> service implementations with dependencies, store those dependencies into
>>> final fields. Once we're all running
>>> on 100 core workstations, you'll thank me. Seriously, Java's memory
model
>>> is seriously twisted stuff, and
>>> assigning to a non-final field from a constructor opens up a tiny window
of
>>> non-thread safety.
>>> Comments
>>>
>>> Comments are overwhelmingly important. Try to capture the *why* of a
class
>>> or method. Add lots
>>> of links, to code that will be invoked by the method, to related methods
or
>>> classes, and so forth. For instance,
>>> I'll often have an annotation, a worker class for the annotation, and a
>>> related service all cross-linked.
>>>
>>> Comment the *interfaces* and don't get worked up on the
*implementations*.
>>> Javadoc does a perfectly
>>> good job of copying interface comments to implementations, so this falls
>>> under the *Dont Repeat Yourself*
>>> guideline.
>>>
>>> Be very careful about documenting what methods can accept null, and what
>>> methods may return null. Generally
>>> speaking, people will assume that null is not allowed for parameter and
>>> method will never return null, unless
>>> it is explicitly documented that null is allowed (or potentially
returned).
>>> Documentation
>>>
>>> Try and keep the documentation up-to date as you make changes; it is
*much
>>> * harder to do so later. This is now much easier using the Confluence
wiki
>>> (you're reading it ).
>>>
>>> Documentation is the *#1 criticism* of Tapestry!
>>> Class and Method Naming Conventions
>>>
>>> aming things is hard. Names that make sense to one person won't to
another.
>>>
>>> hat being said, I've tried to be somewhat consistent with naming. Not
>>> perfectly.
>>> Factory, Creator
>>>
>>> A factory class creates new objects. Methods will often be prefixed with
>>> "create"
>>> or "new". Don't expect a Factory to cache anything, it just creates new
>>> things.
>>> Source
>>>
>>> A source is a level up from a Factory. It *may* combine multiple
factories
>>> together.
>>> It *usually* will cache the result. Method are often prefixed with
"get".
>>> Find vs. Get
>>>
>>> For methods: A "find" prefix indicates that a non-match is valid and
null
>>> may be returned.
>>> A "get" prefix indicates that a non-match is invalid and an exception
will
>>> be thrown
>>> in that case (and null will never be returned).
>>> Contribution
>>>
>>> A data object usually associated with a Tapestry IoC service's
>>> configuration.
>>> Filter
>>>
>>> Part of a pipeline, where there's an associated main interface,
>>> and the Filter wraps around that main interface. Each main interface
>>> method is duplicated in the Filter, with an extra parameter used
>>> to chain the interface.
>>> Manager
>>>
>>> Often a wrapper around a service configuration, it provides access
>>> to the contributed values (possibly after some transformation).
>>> To
>>>
>>> A method prefix that indicates a conversion or coersion from one type to
>>> another. I.e., toUserPresentable().
>>> Worker
>>>
>>> An object that peforms a specific job. Workers will be stateless, but
will
>>> be passed
>>> a stateful object to perform some operation upon.
>>> Builder
>>>
>>> An object whose job is to create other objects, typically in the context
of
>>> creating a core service implementation for a Tapestry IoC service (such
as
>>> PipelineBuilder
>>> or ChainBuilder).
>>> Support
>>>
>>> An object that provides supporting operations to other objects; this is
a
>>> kind of "loose aggregation".
>>> Parameters
>>>
>>> A data object that holds a number of related values that would otherwise
be
>>> separate
>>> parameter values to a method. This tends to streamline code (especially
>>> when using
>>> a Filter interface) and allows the parameters to be evolved without
>>> changing the method signature.
>>> Strategy
>>>
>>> An object that "plugs into" some other code, allowing certain decisions
to
>>> be deferred
>>> to the Strategy. Often a Strategy is selected based on the type of some
>>> object
>>> being operated upon.
>>> Context
>>>
>>> Captures some stateful information that may be passed around between
>>> stateless services.
>>> Constants
>>>
>>> A non-instantiable class that contains public static fields that are
>>> referenced in multiple places.
>>> Hub
>>>
>>> An object that allows listeners to be registered. Often includes a
method
>>> prefixed with "trigger"
>>> that will send notifications to listeners.
>>> Implement toString()
>>>
>>> Objects that are exposed to user code should generally implement a
>>> meaningful toString() method.
>>> And that method should be tested.
>>> Subclassing
>>>
>>> You'll notice there isn't a lot of inheritance in Tapestry. Given the
>>> function of the IoC container,
>>> it is much more common to use some variation of *aggregation* rather
than
>>> *inheritance*.
>>>
>>> Where subclassing exists, the guideline for constructor parameters is:
the
>>> subclass should include all
>>> the constructor parameters of the superclass, in the same positions.
Thus
>>> subclass constructor parameters
>>> are appended to the list of super-class constructor parameters.
>>> Change Notification Preferences<
https://cwiki.apache.org/confluence/users/viewnotifications.action>
>>> View Online<
https://cwiki.apache.org/confluence/display/TAPESTRY/Developer+Bible>
>>>
>>
>>
>>
>> --
>> --
>> http://www.bodylabgym.com - a private, by appointment only, one-on-one
>> health and fitness facility.
>> --
>> http://www.ectransition.com - Quality Electronic Cigarettes at a
reasonable
>> price!
>> --
>> TheDailyTube.com. Sign up and get the best new videos on the internet
>> delivered fresh to your inbox.
>>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [email protected]
> For additional commands, e-mail: [email protected]
>
