[jboss-dev-forums] [Embedded JBoss Development] - Re: Embedded API Design Problems

[david.lloyd@jboss.com]

"richard.opalka at jboss.com" wrote : Please take it as feedback and not hassling ;)
  | 
  | INCONSISTENT METHOD NAMES
  | 
  |  * ISSUE 1: Many Embedded project classes/intefaces follow BEAN naming convention but there are some exceptions.
  | 
  |  * RULE 1:  API should be consistent. Once you're following BEAN naming convention, whole API must apply to this rule.
  | 

I buy this, even with builder-pattern-like things.  Mutators should have "set" in front of them, even if they return "this" for use in method call chaining.

BTW, rather than using a generic type paramter representing "this class", you should just leverage covariant return types and have each subtype override the return type with its more specific type.  With the generic parameter this is being done anyway; the difference is, now users often have to deal with the onerous and obnoxious "this" type parameter.  Any time you have "Foo<T extends Foo<T>>" that should be a warning to proceed with caution.

"richard.opalka at jboss.com" wrote : 
  | DO NOT DECLARE TO THROW RUNTIME EXCEPTIONS
  | ...
  |  * RULE 2.5: Runtime exceptions indicate programmer errors. The best practice is to don't declare them in method signature.
  | 

Couldn't disagree more.  Putting all possible/expected unchecked exception types in the throws clause gives users a sense of what to expect; also it can hint to IDEs that you might want to add a catch clause for it.  And it does no real harm.

"richard.opalka at jboss.com" wrote : 
  |  * shouldn't be declared to be thrown from API if it is assignable from java.lang.RuntimeException and represents programmer error
  | 

Again, disagree.


View the original post : http://www.jboss.org/index.html?module=bb&op=viewtopic&p=4268850#4268850

Reply to the post : http://www.jboss.org/index.html?module=bb&op=posting&mode=reply&p=4268850