Developer BiblePage edited by Kalle KorhonenChanges (1)
Full ContentThis is a semi-random outpouring of thoughts related to being a Tapestry committer. IDEIntelliJIt's a free license for all committers and it's just better. Yes, the first few days There are shared code formatting settings in <support/idea-settings.jar>. This will prevent EclipseHoward uses this ... because he can't manage to switch IDEs constantly (he uses Eclipse for training). Lately CopyrightsAll source files should have a copyright comment on top, except where such a comment The year on the copyright should be updated as a file changes. As you are reviewing your changes Commit MessagesAlways provide a commit message. I generally try to work off the JIRA, so my commit message is often:
It is very important to include the JIRA issue id in the commit. This is used in many places: JIRA ProceduresAll Tapestry committers should be registerred with JIRA and part of the tapestry-developers JIRA group. I work the following JIRA list: JIRA Work Queue. Ideally, we would always work top priortity to low priority. I (Howard) sometimes jump out of order, Starting workWhen you start to work on an issue, make sure it is assigned to you and use the start progress 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 I often update the issue description to make it more legible and more precise, i.e., "NPE in CheckUpdates" Closing bugsIs it a bug fix without tests? No. In some cases, I write new tests to prove that an issue is not valid and A good plan is to write a test that fails then work the code until the test passes. 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 For anything non-trivial, wait for the Hudson CI server to build. It catches a lot of things ... such as Invalid issues and duplicatesAlways 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 CopyrightsThe ASF copyright must appear on all Java source files. Technically it should appear on all non-binary As you make changes to files, update the copyright to add the current year to the list. The goal is that the copyright IntelliJ has a great comparison view: Cmd-9 to see the local changes, the Cmd-D to see the differences. Public vs. Private/InternalThis is a real big deal. As long as code is in the internal package, we have a high degree of carte-blanche Interfaces are public, implementations are private. You can see this is the bulk of the code, where 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 Evolving ComponentsWe do not have a specific plan for this yet. Future Tapestry 5 will add features to allow clean renames Evolving InterfacesTapestry 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 InterfacesNew methods may be added if absolutely necessary, but this should be avoided if at all possible. Don't forget Consider having a stable public facade service whose implementation calls into one or more internal service. User InterfacesThese should be frozen, no changes once released. Failure to do so causes non-backwards compatible upgrade problems; 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 Use of @sinceWhen 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 StyleYes, at one time I (Howard) used leading underscores for field names. I've since changed my mind, but 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 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 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 CommentsComments are overwhelmingly important. Try to capture the why of a class or method. Add lots Comment the interfaces and don't get worked up on the implementations. Javadoc does a perfectly Be very careful about documenting what methods can accept null, and what methods may return null. Generally DocumentationTry 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 Conventionsaming 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, CreatorA factory class creates new objects. Methods will often be prefixed with "create" SourceA source is a level up from a Factory. It may combine multiple factories together. Find vs. GetFor methods: A "find" prefix indicates that a non-match is valid and null may be returned. ContributionA data object usually associated with a Tapestry IoC service's configuration. FilterPart of a pipeline, where there's an associated main interface, ManagerOften a wrapper around a service configuration, it provides access ToA method prefix that indicates a conversion or coersion from one type to another. I.e., toUserPresentable(). WorkerAn object that peforms a specific job. Workers will be stateless, but will be passed BuilderAn object whose job is to create other objects, typically in the context of SupportAn object that provides supporting operations to other objects; this is a kind of "loose aggregation". ParametersA data object that holds a number of related values that would otherwise be separate StrategyAn object that "plugs into" some other code, allowing certain decisions to be deferred ContextCaptures some stateful information that may be passed around between stateless services. ConstantsA non-instantiable class that contains public static fields that are referenced in multiple places. HubAn object that allows listeners to be registered. Often includes a method prefixed with "trigger" Implement toString()Objects that are exposed to user code should generally implement a meaningful toString() method. SubclassingYou'll notice there isn't a lot of inheritance in Tapestry. Given the function of the IoC container, Where subclassing exists, the guideline for constructor parameters is: the subclass should include all
Change Notification Preferences
View Online
|
View Changes
|
- [CONF] Apache Tapestry > Developer Bible confluence
- [CONF] Apache Tapestry > Developer Bible confluence
- [CONF] Apache Tapestry > Developer Bible confluence