Hi Hargrave I agree with you, however we are porting an existing framework from C++ to Java and so we cannot freely change method names in order to comply to Sun/Java conventions. Our conventions are product driven and target audience driven, instead.
We try to keep our API as close as possible to QuantLib/C++, keeping the same object model, hierarchy, method names and field names. because we are targeting those users willing to easily port their code written for QuantLib/C++ to JQuantLib/Java. Obviously there are circumstances, like C++ operator overloading and C++ templates (among others) which cannot be directly translated to Java. In such circunstances we obviously need to adapt certain things. Another circumstance would be the need to get rid of statics on top of OSGi containers. That's the reason of my question: learn from the community what would be the best practices on it and adopt what the community agrees as excellent. Kind Regards Richard Gomes M: +44(77)9955-6813 http://www.jquantlib.org/index.php/User:RichardGomes twitter: frgomes JQuantLib is a library for Quantitative Finance written in Java. http://www.jquantlib.org/ twitter: jquantlib BJ Hargrave wrote: > I think as a user of an API, you rarely care if a method is a static > method or not. What you care about is what happens. What happens is > described by the name of the method and the documentation of the > method. This is why method naming is very important since it is an > important conveyer of the semantics of the method. > > For example, todaysDate is a poor method name in my opinion. It does > not tell me enough about the method. Is it changing the receiver to > reflect today's date? Is it returning a shared Date object for today? > Is is returning a new Date object for today? Of course that > information must be in the methods documentation, but the method name > should also convery more information. > > getTodaysDate tells me the method is not changing the receiver. > newTodaysDate tells me the method returns a new Date instance. Theses > are just examples of how good method naming really helps in conveying > important semantic information. > -- > > *BJ Hargrave* > Senior Technical Staff Member, IBM > OSGi Fellow and CTO of the _OSGi Alliance_ <http://www.osgi.org/>_ > [email protected]_ <mailto:[email protected]> > > office: +1 386 848 1781 > mobile: +1 386 848 3788 > > > > > From: Richard Gomes <[email protected]> > To: [email protected] > Date: 2009/09/15 12:20 > Subject: Re: Re: [osgi-dev] Best practices regarding 'static' > variables and methods > Sent by: [email protected] > > > ------------------------------------------------------------------------ > > > > Hi Hargrave > > Thanks a lot for your quick answer. > > The use case I provided is only for the sake of example. Our static > methods do much more than that! :) > > You are correct regarding 'promoting' certain static methods to > non-static methods and that's it! > Yeah... there are several situations in the code I'm working on where an > instance variable is interested on some processing performed by a static > method. In this case, an instance variable is typically passed as > argument to the static method. Just to give you a couple of examples, > I've defined some convenience methods which are intended to provide > certain functionalities to instance variables. Something like this: > > > /** > * Convenience method to {...@link Statics#isLeap(int)} > */ > public final boolean isLeap() { > return statics.isLeap(year()); // obtains 'year' from 'this' and > calls isLeap(year) > } > > /** > * Convenience method to {...@link Statics#endOfMonth(Date)} > */ > public final Date endOfMonth() { > return statics.endOfMonth(this); // a bridge to a static method > } > > > On the other hand, on certain circumstances, having an instance method > will "give an incorrect idea" that a certain functionality is operating > on an instance variable, whilst it's not the case. These are a couple of > examples of static methods turned to instance methods of an inner class > (implementing the sub interface): > > /** > * Today's date. > * > * @return a new instance > */ > public final Date todaysDate() { > final java.util.Calendar cal = > java.util.Calendar.getInstance(); > final int d = cal.get(java.util.Calendar.DAY_OF_MONTH); > final int m = cal.get(java.util.Calendar.MONTH); > final int y = cal.get(java.util.Calendar.YEAR); > return new Date(d, m + 1, y); > } > > /** > * Earliest allowed date > * > * @return a new instance > */ > public final Date minDate() { > return new Date(MinimumSerialNumber); > } > > Observe "@return a new instance". But, if I provide such methods as > instance methods of the outer class, the call would be: > > Date date = ...; // obtain some date somehow > Date today = date.todaysDate(); > > ... which seems weird and may cause confusion because the developer > needs to "remember" that todaysDate() creates a new instance instead of > changing 'this' instance (the 'date' variable). > > Obviously we can say that documentation is there to help developers to > "remember" but IMHO "having to remember" is bad by definition because > when you don't remember... you end up with a bug in your code. > So, calls such as: > > (1) Date today = date.statics().todaysDate(); // and ... > (2) Date today = statics.todaysDate(); // where 'statics' was > injected by DS, being sub interface of Date > > explains much more about what is happening under the covers. > > Other methods I mentioned in the beginning can be called as instance > methods or typically as static methods, depending on the use case, like > this: > > (1) if (date.isLeap()) { ... } // instance method > (2) if (xyz.isLead(1999)) {...} // mimics static method; part > of the sub-interface > > I hope I had explained the technical reasons for keeping some methods > intentionally separated in a sub interface. > > Kind Regards > > Richard Gomes > M: 44(77)9955-6813 > http://www.jquantlib.org/index.php/User:RichardGomes > twitter: frgomes > > Jquantlib is a library for Quantitative Finance written in Java. > http://www.jquantlib.org/ > twitter: jquantlib > > > (I had to copy/paste your message :~ I've changed from digest to > individual messages now! ) > ================================================================== > > BJ Hargrave wrote: > > I guess my first question is why do you need a static method to access a > static field? Just use a normal interface method whose implementation > operates on a static field. > > public interface ABC { > public int getA(); > public double getX(); // provides access to static field X; > } > > public class ABCimpl implements ABC { > private int a = 10; > public int getA() { a++; return a; } > > private static final x = 1.2; > public double getX() { return x; } > } > -- BJ Hargrave > Senior Technical Staff Member, IBM OSGi Fellow and CTO of the OSGi > Alliance > [email protected] > office: +1 386 848 1781 > mobile: +1 386 848 3788 > > _______________________________________________ > OSGi Developer Mail List > [email protected] > https://mail.osgi.org/mailman/listinfo/osgi-dev > > ------------------------------------------------------------------------ > > _______________________________________________ > OSGi Developer Mail List > [email protected] > https://mail.osgi.org/mailman/listinfo/osgi-dev
_______________________________________________ OSGi Developer Mail List [email protected] https://mail.osgi.org/mailman/listinfo/osgi-dev
