I have thought about writing up a section of the documentation focussed on
developers. Too many guidelines and rules turns people off though and we
really want to encourage new devs and not create barriers. Experienced
programmers will look at the existing code and adapt to the existing coding
style. New ones may not appreciate being informed about style guidelines
when this is their first C++ code. There's a balance there of course.
I would love every pull request to be accompanied by docs and tests.
Enforcing this is a different matter. We do this in cclib as we have had a
test driven culture from the start and all of the devs can see the value.
It could be that we don't enforce it for the first few pull requests but
require it after that - I.e. have a grace period.
By the way, the api docs are built with "make docs" I believe. Naturally
this is not documented :-)
On 26 Jun 2016 8:46 p.m., "Stefano Forli" <fo...@scripps.edu> wrote:
> 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
