Can we come up with a shorter name for reference sequences? about ga4gh-schemas HOT 8 CLOSED

GARefSeqSet, or we can go to a Hungarian naming convention :) I think there will be encapsulation in these classes right? That will by definition will make it more modular and simple. Just my $0.02 :)

from ga4gh-schemas.

-1
Code completion like intellisense makes long names easy to handle. And implementations should be auto-generated from the schema, so hand-typing is minimal. I'd keep it as it is for 0.5.

from ga4gh-schemas.

An API name is more important than just a class that autocompletes in code. We also have to consider the urls that get exposed, the documentation that surrounds the API, how hard it is for brand new users to understand concepts, how readable a piece of sample code is after its been written, etc.

All of these examples are actually more important than how easy it is to write the code itself. As you said, there is autocomplete for most languages, so it doesn't matter as much what the class is called from that perspective.

This on the other hand:
/referencesequencesets/search

is very affected by the name of the object.

And writing good documentation on what objects mean, like this page, also benefits from simple, concise, concepts, that use consistent patterns.

from ga4gh-schemas.

Imo the schema is the best documentation, descriptive names are self explanatory. This is important during the design phase (pre 1.0) where changes are frequent and expected to be lightweight. Tracking changes in two different places is not lightweight, and from comments it seems new users spend more time fighting git than understanding the schema.

/referencesequencesets/search - so what's wrong with this URL? Search engines should be able to index it and normal users are not supposed to type it in.

from ga4gh-schemas.

Usually "overly long verbose names" are not encouraged (i.e. BioPerl, GATK Coding Standards, etc.)

Anyway, usually in designing frameworks and APIs the most stable designs go from general to specific. If something becomes too long it means that it can modularized into super- and subclasses with appropriate encapsulation.

Why not just separate it like this - we could even have backend URL rewrites, but it would be better if it matches the actual entity-relationship model:

/sequence/sets/reference/search

/sequence/reference/sets/search

from ga4gh-schemas.

I'd be in favour of less verbose class names also, pretty much for the reasons Cassie outlined above. I guess the question to ask is, is the Sequence in ReferenceSequenceSet redundant? I.e., could a ReferenceSet be reasonably confused for something else in this general context?

from ga4gh-schemas.

I like Reference and ReferenceSet.

The alternative of RefSeq is not so good because it is an informal brand name of NCBI.

Richard

Sent from my iPhone

On 7 Jul 2014, at 09:43, Jerome Kelleher [email protected] wrote:

I'd be in favour of less verbose class names also, pretty much for the reasons Cassie outlined above. I guess the question to ask is, is the Sequence in ReferenceSequenceSet redundant? I.e., could a ReferenceSet be reasonably confused for something else in this general context?

—
Reply to this email directly or view it on GitHub.

The Wellcome Trust Sanger Institute is operated by Genome Research
Limited, a charity registered in England with number 1021457 and a
company registered in England with number 2742969, whose registered
office is 215 Euston Road, London, NW1 2BE.

from ga4gh-schemas.

I have sent you a fax message. Please check document attached.

from ga4gh-schemas.