Noel, thanks for the reply, I had some time to think about your email and the issue, here are a few points to discuss. I like the concept of necessity could be the seed around which guidelines could be built... once we define explicitly what "necessary" means. An initial structure for the guidelines could be:
1. Define what criteria would we use to consider a function necessary. Once that's clarified, it should be easier to prevent unnecessary changes to the API's. 2. If an API gets modified and becomes more complex (i.e., more optional parameters?) defaults should be set such that the new behavior mimics the old API. 3. Functions should be written to be small, and do a single operation while keeping the code simple. If the function code gets too large, it should be broken down into smaller, helper functions. These helper functions should be reusable, but kept private as much as possible, preventing the proliferation of new API's. 4. Some code styling should also be enforced. I found the idTech 4 coding standard (used by id software [1,2]) to be incredibly useful and a remarkable source of inspiration. This should be extended to the specific needs of OpenBabel. For example, encourage using iterators in macros vs building our own. Not sure if this is really important, and I've seen using both ways indiscriminately (I suspect geological stratification of new code over old one), but I think would be easier on the code base, preventing the reinvention of the wheel and the potential inclusion of new bugs. 5. I have no experience whatsoever on compilation, warnings and such, but given the recent discussion in the mailing list, I believe it would be good to provide a clear and standard set of options needed to compile the code in way that makes it acceptable for incorporation in the main branch and redistribution. 6. Documentation. If new code is added, it *must* be documented. I found very hard (for a rookie, though) to understand how documentation is added and maintained. I believe there's a way to generate documentation directly from comments in the code, and I will be really happy to be able to do that. [1] http://kotaku.com/5975610/the-exceptional-beauty-of-doom-3s-source-code [2] ftp://ftp.idsoftware.com/idstuff/doom3/source/codestyleconventions.doc Needless to say, all these points are just suggestions. There's a lot more to be said on the matter, and I trust more experienced coders to improve this stub. Best, S -- Stefano Forli, PhD Assistant Professor of Integrative Structural and Computational Biology, Molecular Graphics Laboratory Dept. of Integrative Structural and Computational Biology, MB-112F The Scripps Research Institute 10550 North Torrey Pines Road La Jolla, CA 92037-1000, USA. tel: +1 (858)784-2055 fax: +1 (858)784-2860 email: fo...@scripps.edu http://www.scripps.edu/~forli/ ________________________________________ From: Noel O'Boyle [baoille...@gmail.com] Sent: Tuesday, June 21, 2016 12:16 PM To: Geoffrey Hutchison Cc: David van der Spoel; Openbabel-DEV; Stefano Forli Subject: Re: [OpenBabel-Devel] OB API/ABI changes Hi Stefano, Your comment about guidelines is of course true. I've been thinking about this. My feeling is that only needed functions should be in the API. So it's not that a function is not useful, or that someone might find it useful. This is not a concrete guideline of course, but it's something to bear in mind. Regards, - Noel On 2 June 2016 at 16:34, Geoffrey Hutchison <geoff.hutchi...@gmail.com> wrote: >> SMARTS pattern is that you have the match of each atom to each virtual >> atom of the pattern. For a function of OBAtom, it's just boolean true >> or false. > > Moreover, there's already OBAtom::MatchesSMARTS() > http://openbabel.org/dev-api/classOpenBabel_1_1OBAtom.shtml#abfdefac42d3c895920f1f715f0d710a5 > > Some of these "one-off" functions are certainly more efficient, and I do like > David's enum-based suggestion. > > My feeling is that we should decide fairly quickly on any API changes so that > we can issue 2.4 soon. > > Thanks, > -Geoff ------------------------------------------------------------------------------ Attend Shape: An AT&T Tech Expo July 15-16. Meet us at AT&T Park in San Francisco, CA to explore cutting-edge tech and listen to tech luminaries present their vision of the future. This family event has something for everyone, including kids. Get more information and register today. http://sdm.link/attshape _______________________________________________ OpenBabel-Devel mailing list OpenBabel-Devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/openbabel-devel
