tapestry-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Kalle Korhonen <kalle.o.korho...@gmail.com>
Subject Re: [CONF] Apache Tapestry > Developer Bible
Date Fri, 01 Oct 2010 00:58:10 GMT
I see - but cwiki accounts are separate from Apache accounts, so just sign up.

Kalle


On Thu, Sep 30, 2010 at 5:52 PM, Josh Canfield <joshcanfield@gmail.com> wrote:
> Yep, but I'm still waiting for my account...
> On Sep 30, 2010 4:52 PM, "Kalle Korhonen" <kalle.o.korhonen@gmail.com>
> wrote:
>> Fixed. Faster to fix yourself than send an email, no?
>>
>> Kalle
>>
>>
>> On Thu, Sep 30, 2010 at 3:31 PM, Josh Canfield <joshcanfield@gmail.com>
> wrote:
>>> typo in Copyright section:  "try to check the coyright date"
>>>
>>> On Thu, Sep 30, 2010 at 2:49 PM, <confluence@apache.org> 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: dev-unsubscribe@tapestry.apache.org
>> For additional commands, e-mail: dev-help@tapestry.apache.org
>>
>

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tapestry.apache.org
For additional commands, e-mail: dev-help@tapestry.apache.org


Mime
View raw message