New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Conformity with common programming standards #79
Comments
Javabeans Sets vs Lists I'm not sure I'm understanding your comment though about casting to Collection types. Can you elaborate please? Thanks for the feedback and suggestions. I'd like to know what you think. |
Javabeans
I assume applying the JavaBean pattern is a common coding paradigm in the IT industry and should also be best practice for open source software like gedcom4j. The JavaBean pattern additionally simplifies the integration with other frameworks. Sets vs Lists Another aspect of using E.g. adding a distinct |
Unfortunately, changing from One solution being discussed is a List implementation that does not allow duplicate entries in order to maintain the current API and backwards compatibility. Design aspects, theories, idioms, and religions aside, backwards compatibility is one of the main goals of this library. Considering that the project uses Semantic Versioning in all but name, it would be able to break backwards compatibility if the major version number is incremented. Without incrementing the major version number, it should not break backwards compatibility. |
I think that an inner List implementation that prevents duplicates is probably the most API-neutral way to accomplish the goal of preventing duplicates, although to jtroester's point, it doesn't do much in terms of information hiding. In general, I'm not really very worried about consumers of the API having visibility to its internals, to be honest, so that is the main reason the project hasn't done more to hide its internals as it has grown organically over the years. This is really the first time anyone has seriously suggested it in the five years since I first released the project; but then, a library for reading/writing/manipulating GEDCOMs without providing any user interface is a pretty niche product, and as far as I know, the number of users has yet to make it into triple digits. I also think it is clearly debatable whether the JavaBeans spec is advisable here. It's easy to find cogent arguments on both sides by respected leaders in the field. If information hiding does become an important design goal of the project -- and I am open to that -- then JavaBeans would be the way to go, along with changing the API to use Collection rather than List/Set, etc. Such a shift would be a general style change, where protecting and hiding internals would become an overall project design goal, and we'd look at how best to do that across the entire project. Arguments to bring information hiding into gedcom4j will be more persuasive if they are based on specific problems caused by not hiding information better. For example, "technology X is incompatible with gedcom4j because it only works with JavaBeans but cannot work with public fields of public classes". Such arguments would then be evaluated against specific issues that would definitely be caused by API changes. Arguments based on general principles will be considered as well, but will not carry as much weight as identifying specific ways that the library fails to work, and will have to be compelling enough so that the choice of upgrading and changing their code to remain compatible seems worthwhile to current users. TL;DR: I'm going to leave this issue open so that others can weigh in. I am open to these and other suggestions for future releases, but for the short term I won't be making any changes that would require my existing clients to change their code. If that day comes, it would be a major release change (3.x.x). |
Thanks for all your comments. The gedcom4j project gives me the impression to be a solid foundation for handling a variety of gedcom file flavours and to be suffiently stable for integrating gedcom4j with my work. When working with frameworks I expect some standards to be fulfilled to ease integration and maintainability. To deal with a mix-up of individual API styles complicates effective work. I recognize that from a project owner's point of view there are good reasons to garantuee backward compatibility to all current customers. It's in the nature of things that sooner or later new requirements arise and hence the project's goals have to be balanced out. In order that everyone may benefit from it these are my suggestions that I would like you to consider:
|
Created new Milestone for v3 of gedcom4j, for some future date. Will add other roadmap items to that milestone in addition to the two main items discussed here. Closing this issue in favor of the other two. |
During the last few days I did some testing with the Ahnentafel example and a gedcom file covering about 17.000 individuals. Performance of the parser is quite fine. For further use of the library i'd like to suggest some technical enhancements.
Are there already any considerations about enhancing conformity with common programming standards and patterns?
E.g. fields should be hidden and the API should be exposed on public getter and setter methods according to the JavaBeans pattern,
List/ArrayList types should be replaced with Set/HashSet types wherever duplicates may occur and therefore the API relevant types have to be casted to Collection types in order to hide implementation details in order to avoid explicitly checking if new element is already contained in the collection. This approach requires ordering of elements being out of scope.
If contribution is appreciated please let me know...
The text was updated successfully, but these errors were encountered: