Hi there, As some of you know, I would like to remove all convenience functions from classes in Open Babel. I would like to explain why.
It's hard to exactly define a convenience function, but it's an addition to the API that is implemented entirely using existing API calls and that makes it easier to do certain things. There may be a place for these in the documentation (e.g. usage examples as OEChem does) or in a convenience.cpp, but I argue that they should never be part of any Open Babel classes, and in particular, should never be used internally by the API. One reason is that it clogs up the core API, which affects both compilation speed and reading the API looking for functions. It's also API duplication - there should be one way to do something. Also, there are a infinite number of convenience functions and once you let one in (e.g. OBAtom::IsCarbon()), you must then let in 100+ other ones. A more subtle reason is that they obscure the correct usage of the underlying core API, as users cannot know they are convenience functions. Sounds a bit vague? Here are two examples. Let's take the duplicated std::string versus const char* functions I mentioned in an earlier email. The std::string version just calls the const char* function. Some of these convenience functions do an unnecessary string copy. On top of this, a user of the toolkit, having a char* to hand but needing to choose between the methods, may construct a std::string (another copy) to call the std::string method because stack overflow tells us to always use C++ STL objects. So, adding the convenience functions had the unintended consequence of two string copies. Another example is the convenience function that Stefano has proposed that loops over the Residues to return the PDBAtomId for an OBAtom. I don't disagree this is useful, but it's still a convenience function. Now imagine a user who writes a loop over all the atoms in a molecule calling this function. They end up using an N squared function, which is going to be a fairly significant slowdown for PDB files. But there was no way for them to know that this was not the correct method to call. The current API has many such convenience functions. Let's make a bonfire (e.g. called convenience.cpp) and burn them all. - Noel ------------------------------------------------------------------------------ Check out the vibrant tech community on one of the world's most engaging tech sites, SlashDot.org! http://sdm.link/slashdot _______________________________________________ OpenBabel-Devel mailing list OpenBabel-Devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/openbabel-devel
