Hello David, Le 03/07/2020 à 04:30, David Leangen a écrit : > > [...] > >> I don't believe the code is super clean but it does work and is quite >> efficient and fast. > > Yes, that is important, but again, this comment about being “efficient and > fast” seems perfectly valid for an implementation, but not really for an API. > The API should be more about expressing the model and drawing clear component > boundaries. (It should not preclude a good implementation, of course, but > should usually not force a particular implementation either.) > >> I agree with the coupling and it is going to take some effort to go >> through all of the modules and clean them up. > > Since I am pretty much stuck with the documentation efforts (as I have > mentioned I need more input from the community if I am to move forward), what > I think I’ll try to do next is write an “independent” API for SMTP. My hope > is that this will:
>From what I recall, business class exposed by the API are pretty well defined: it exposes some hooks one could implement. The big issue here is more that the protocols-smtp project does mix together the "port" (as in hexagonal architecture) and the implementation / wiring of it. I believe, from a documentation perspective much can be achieved by extracting a 'protocols-smtp-api' exposing the classes I can implement as a protocols-smtp user, and having the actual smtp protocol implementation in a separated project. I believe Gradle will also make this "API extraction" easier. As part of your documentation effort, I can provide a listing of such classes; while waiting for the module extraction. > > * Provide an example as to how to write a “clean” and independent API > * Help with documentation (because in a way, the API **is** the > documentation because it should reflect the model very well) Here I have several concerns: - We should document what exist, and not a possible desirable future state that may not be reached. I believe if some reasonably easy moves could be done to ease the documentation process, we should give it a go. (The above proposal tries to achieve this) > * Continue to use the “existing” code that “does work and is quite efficient > and fast” to implement the new API > > In the worst case we can throw it away, in the best case it will provide an example of how to move forward with better componentization of James. Here I'm concerned. Not that throwing code and rewritting things is a bad idea, but it needs to be seen as an investment. The question I would ask myself is "what do we gain from it?" "what are the costs?" and "Is it the right moment to do that investment". Now, protocolHandlers is a widely used API to extend James behavior and we should pay special care about API stability to prevent our users to rewritte their extensions. Regards, Benoit --------------------------------------------------------------------- To unsubscribe, e-mail: server-dev-unsubscr...@james.apache.org For additional commands, e-mail: server-dev-h...@james.apache.org
