Both recommended in the official Mobx page if one wants an opinionated way to using mobx for state management.
Based on these(1,2), keystone seems like an improvement of state-tree. Having everything that state-tree has + more. Nowhere I could find anything that state-tree has that keystone doesn't.
I see keystone is nowhere nearly as mature as state-tree. That's probably the main point stopping me from picking it instead. What are other good points for state-tree over keystone?
P.S. It's going to be used in a React app.
I'm the current maintainer of MobX-State-Tree. I think the primary benefit of MST over MobX-Keystone is that MST is used more widely and has more broad third-party support. For example, mobx-devtools supports MST but not MobX-Keystone, as does Reactotron.
With all that said, I'm very interested in exploring MobX-Keystone for our own usage at my consulting company. Even though I'm maintaining MST, I'm not opposed to MobX-Keystone, and the much better TypeScript support is very tempting. If we end up using it in a project and it goes well, we will likely build in support to Reactotron for it.
I hope this perspective helps.
(With regard to the other answer asking if you really need more than just MobX, it's my opinion that MST and MobX-Keystone bring super useful patterns and tools that help you scale across a whole application in a more cohesive way than remaking them yourself using MobX.)
First ask yourself if you really need those libraries, because you can get really far with just mobx and good ol' OOP patterns. In the official docs you have an example of a store that does auto-saving and serializing.
Having said that, I would go for the mobx-keystone. Typescript works right out of the box, and you can use classes to construct your store, which is IMHO, easier that MST stores. Plus the author is very responsive and he is also a contributor to mobx library.
mobx-keystone is super awesome. After using both of the two libraries for a while I would recommend using it over mobx-state-tree in every possible occasions. It's much more intuitive and easer to learn. It saved a lot of time for my project (switching from zustand to jotai to mobx-keystone, IMO each next one is a bit better than previous one in my use case)
After extensive testing / reading the source code / playing with test suite it feels that mobx-keystone provides a more robust developer experience with Typescript and also has enough escape hatches if you need to work with performance sensitive code. I would implementing a small problem (but complex enough) problem with both libraries to judge for yourself.
Related
With the next closing of SqueakSource repository, I wonder what is the advantage of SmalltalkHub over SqueakSource3. Is there some feature missing in SqueakSource3?
I have noticed that basic functionality like explore projects seems broken in SmalltalkHub, which is understandable because it is still in beta, but why to move or register projects to SmalltalkHub then?
Pharo's core development happens completely on SmalltalkHub.
It is much faster than SqueakSource3, which is the main point in favor of it. SmalltalkHub is still being extended and new features are on the way. For a typical use case from the image side there is little or no difference between the two.
SmalltalkHub is faster than SS3. It has a new look. You can manage team and collaborators with a modern interface. Nicolas Petton uses it daily for work and in addition it will continue to enhance it. All the Pharo core packages are hosted there. Finally, you can also easily install and use SmalltalkHub in your company if you need it. The software stack behind SmalltalkHub is really robust and nice. Several companies uses it for other projects.
From a risk-avoidance POV, there is something to be said for storing them in both. Their software stacks and feature sets are sufficiently different. Just make sure you identify one as primary. Copying the monticello files from one repository to the other is easily automated. Stef provided some scripts to copy whole projects from squeaksource to smalltalkhub recently, they would equally well work for canary or ss3.
I work in a small organization that has built an enterprise SaaS solution. Up until this point our workflows have had no programmatic interface. We're moving to a model that will allow for an end user to do anything programmatically that can be done in the UI. I'm looking for suggestions in terms of the language/framework that you would use to build that programmatic layer.
From an organizational perspective I would like the current UI team to also have ownership of the API. That team is familiar with PHP, Rails, and Javascript. Our current back-end code is written in Scala. I'm leaning toward not doing the APIs in Scala because it doesn't seem like the right tool for the job and the lack of subject matter expertise around it on the UI team.
From a functionality perspective most of the APIs will be fairly simple database operations (CRUD) with perhaps some simplistic business logic applied on top (search for example).
I'm a bit intrigued by using Node.js for this as everyone on the team is really strong with Javascript. That being said I don't just want to hop on the semi-new technology bandwagon. Because it is enterprise software, unit testing frameworks, reusability, and extendability are all important considerations as well.
Any suggestions?
I realize this question was about technology options, but there's a fundamental concern that seems really important to call out:
From an organizational perspective I would like the current UI team to also have ownership of the API.
While this sounds like a logical approach, it may not work out well unless you're UI team is made up of really solid engineers. SaaS API development is arguably one of the most challenging aspects of modern software design. A great API will make everyone's lives easier, while a poor API will bring your system to its knees and leave you completely clueless as to why.
As a quick example, if you don't solve the end user's needs in the right way, you're likely to force a number of n+1 problems on them (and thus, on you.)
There is a bunch of great material out there about how to design great APIs and even more about the pitfalls of designing a bad one. Generally speaking, most of the UI devs I've worked with, particularly ones that are only familiar with scripting languages, are not people I would entrust to API design. Instead I would utilize them as customers (in a Scrum sense) who guide the design by describing end-user needs.
I faced something like this on a previous project, where we ended up going with a combo of Esper and our own DSL written using ANTLR 3.0. Our biggest concern with using a fully funcional runtime, was sandboxing the user's code.
That said, I think Node.JS would be one of the easier ones to sandbox and it fits your needs. Maybe using something like this: http://gf3.github.com/sandbox/ or looking into Cloud9's code to see how they keep things safe. I also like that with Node.js you could give your users a pretty niffy editor using Ace.
Also check out this post: How to run user-submitted scripts securely in a node.js sandbox?
I maintain in-house business software for a living. Technologies included here are Java, Struts, Spring MVC, jsp, wicket, and a few others. I think it's time to branch out and learn something new.
I am hoping to show myself with a side project that writing code can, in fact, be fun (in some plane of the universe), and that I haven't wasted the past few years of my life doing something I can never love or have fun doing.
I'm thinking of having a fantasy-sport style web site - obviously much, much smaller with regards to features and all that. I was hoping I could get some recommendations for the newest or cleanest frameworks that will allow me to accomplish such a project. My goals are to work on following a real development process instead of just hacking a bunch of crap into an already crappy application on a daily basis. Also I will strive to follow best practices and create good, clean, understandable code that I don't shudder at the thought of having to modify. It's hard to do this at work, because the software I work on has already been developed by 50 guys from various continents that never took the time to design anything before jumping into coding.
I would need a simple database to store users and their picks for each event. Also at my job, the login security is all handled by another group completely. Do people usually write their own login systems from scratch, or are there open source utilities for that as well? I'd be interested in those, as my site will need to have a user login system, and be secure.
I had ruby and rails installed on my computer the last time I conjured up the motivation for this idea, but that was nixed by a hard drive crash. I figured before I just jumped straight to rails for this idea, that I would get a few other opinions off stack overflow to see if people liked something else that I didn't know about.
Also, if anyone has any good resources for how to think about OO design, I could brush up on that as well. I'm looking for anything that will help me to just think about the design from the start and how to get my thoughts into a diagram. I'd like it not to focus so much on patterns and other principles as much as just how to get started and actually put my thoughts in a professional document that I can use to build my project from. I tried to practice this prior to a card game that I wrote, and it got way too complicated way too fast, and the results ended up being not so great.
I’m more familiar with Django, although like you, the only frameworks I’ve really used are the Java/Struts/Spring/JSP, etc. The automatically generated administration interface in Django is amazing coming from these, and it comes with its own authentication system too.
Unless you’re especially predisposed against Python, I think you should give it a go.
Ruby on Rails, Python on Django, PHP on (not sure -- maybe Zend? or CakePHP?), are probably the most popular frameworks if I understand correctly that you want to learn a new language. If I misunderstood you, and you'd rather stick with Java, GWT seems pretty cool -- it's the only real way to avoid "explicitly" writing Javascript (if you DO want to learn and use some Javascript, I personally am in love with Dojo, but jQuery is substantially more popular: those are two good popular frameworks you should consider, though there are others of course, like for all languages I mentioned so far).
One advantage of picking Python and Django is that they work particularly well with Google App Engine (and with Dojo, too, thanks to the cool dojango project!) -- GAE supports JVM too, now, but it's supported Python for a much longer time and the Python side of it is more solid and complete at this time. So, if that's the technology stack you choose, you get to develop and deploy for free, on highly scalable infrastructure, at least until your app gets more than a few million page views per month -- and you really minimize your system adminsitration hassles, all you do is basically to code and write one simple configuration file.
I asked this question about Microsoft .NET Libraries and the complexity of its source code. From what I'm reading, writing general purpose libraries and writing applications can be two different things. When writing libraries, you have to think about the client who could literally be everyone (supposing I release the library for use in the general public).
What kind of practices or theories or techniques are useful when learning to write libraries? Where do you learn to write code like the one in the .NET library? This looks like a "black art" which I don't know too much about.
That's a pretty subjective question, but here's on objective answer. The Framework Design Guidelines book (be sure to get the 2nd edition) is a very good book about how to write effective class libraries. The content is very good and the often dissenting annotations are thought-provoking. Every shop should have a copy of this book available.
You definitely need to watch Josh Bloch in his presentation How to Design a Good API & Why it Matters (1h 9m long). He is a Java guru but library design and object orientation are universal.
One piece of advice often ignored by library authors is to internalize costs. If something is hard to do, the library should do it. Too often I've seen the authors of a library push something hard onto the consumers of the API rather than solving it themselves. Instead, look for the hardest things and make sure the library does them or at least makes them very easy.
I will be paraphrasing from Effective C++ by Scott Meyers, which I have found to be the best advice I got:
Adhere to the principle of least astonishment: strive to provide classes whose operators and functions have a natural syntax and an intuitive semantics. Preserve consistency with the behavior of the built-in types: when in doubt, do as the ints do.
Recognize that anything somebody can do, they will do. They'll throw exceptions, they'll assign objects to themselves, they'll use objects before giving them values, they'll give objects values and never use them, they'll give them huge values, they'll give them tiny values, they'll give them null values. In general, if it will compile, somebody will do it. As a result, make your classes easy to use correctly and hard to use incorrectly. Accept that clients will make mistakes, and design your classes so you can prevent, detect, or correct such errors.
Strive for portable code. It's not much harder to write portable programs than to write unportable ones, and only rarely will the difference in performance be significant enough to justify unportable constructs.
Even programs designed for custom hardware often end up being ported, because stock hardware generally achieves an equivalent level of performance within a few years. Writing portable code allows you to switch platforms easily, to enlarge your client base, and to brag about supporting open systems. It also makes it easier to recover if you bet wrong in the operating system sweepstakes.
Design your code so that when changes are necessary, the impact is localized. Encapsulate as much as you can; make implementation details private.
Edit: I just noticed I very nearly duplicated what cherouvim had posted; sorry about that! But turns out we're linking to different speeches by Bloch, even if the subject is exactly the same. (cherouvim linked to a December 2005 talk, I to January 2007 one.) Well, I'll leave this answer here — you're probably best off by watching both and seeing how his message and way of presenting it has evolved :)
FWIW, I'd like to point to this Google Tech Talk by Joshua Bloch, who is a greatly respected guy in the Java world, and someone who has given speeches and written extensively on API design. (Oh, and designed some exceptionally good general purpose libraries, like the Java Collections Framework!)
Joshua Bloch, Google Tech Talks, January 24, 2007:
"How To Design A Good API and Why it
Matters" (the video is about 1 hour long)
You can also read many of the same ideas in his article Bumper-Sticker API Design (but I still recommend watching the presentation!)
(Seeing you come from the .NET side, I hope you don't let his Java background get in the way too much :-) This really is not Java-specific for the most part.)
Edit: Here's another 1½ minute bit of wisdom by Josh Bloch on why writing libraries is hard, and why it's still worth putting effort in it (economies of scale) — in a response to a question wondering, basically, "how hard can it be". (Part of a presentation about the Google Collections library, which is also totally worth watching, but more Java-centric.)
Krzysztof Cwalina's blog is a good starting place. His book, Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, is probably the definitive work for .NET library design best practices.
http://blogs.msdn.com/kcwalina/
The number one rule is to treat API design just like UI design: gather information about how your users really use your UI/API, what they find helpful and what gets in their way. Use that information to improve the design. Start with users who can put up with API churn and gradually stabilize the API as it matures.
I wrote a few notes about what I've learned about API design here: http://www.natpryce.com/articles/000732.html
I'd start looking more into design patterns. You'll probably not going to find much use for some of them, but as you get deeper into your library design the patterns will become more applicable. I'd also pick up a copy of NDepend - a great code measuring utility which may help you decouple things better. You can use .NET libraries as an example, but, personally, i don't find them to be great design examples mostly due to their complexities. Also, start looking at some open source projects to see how they're layered and structured.
A couple of separate points:
The .NET Framework isn't a class library. It's a Framework. It's a set of types meant to not only provide functionality, but to be extended by your own code. For instance, it does provide you with the Stream abstract class, and with concrete implementations like the NetworkStream class, but it also provides you the WebRequest class and the means to extend it, so that WebRequest.Create("myschema://host/more") can produce an instance of your own class deriving from WebRequest, which can have its own GetResponse method returning its own class derived from WebResponse, such that calling GetResponseStream will return your own class derived from Stream!
And your callers will not need to know this is going on behind the scenes!
A separate point is that for most developers, creating a reusable library is not, and should not be the goal. The goal should be to write the code necessary to meet requirements. In the process, reusable code may be found. In that case, it should be refactored out into a separate library, where it can be reused in the future.
I go further than that (when permitted). I will usually wait until I find two pieces of code that actually do the same thing, or which overlap. Presumably both pieces of code have passed all their unit tests. I will then factor out the common code into a separate class library and run all the unit tests again. Assuming that they still pass, I've begun the creation of some reusable code that works (since the unit tests still pass).
This is in contrast to a lesson I learned in school, when the result of an entire project was a beautiful reusable library - with no code to reuse it.
(Of course, I'm sure it would have worked if any code had used it...)
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
I am converting an open source Java library to C#, which has a number of methods and classes tagged as deprecated. This project is an opportunity to start with a clean slate, so I plan to remove them entirely. However, being new to working on larger projects, I am nervous that the situation will arise again. Since much of agile development revolves around making something work now and refactoring later if needed, it seems like deprecation of APIs must be a common problem. Are there preventative measures I can take to avoid/minimize API deprecation, even if I am not entirely sure of the future direction of a project?
I'm not sure there is much you can do. Requirements change, and if you absolutely have to make sure that clients of the API are not broken by newer API version, you'll have rely on simply deprecating code until you think that no-one is using the deprecated code.
Placing [Obsolete] attributes on code causes the compiler to create warnings if there are any references to the obsolete methods. This way clients of the API, if they are diligent about fixing their compiler warnings, can gradually move to the new methods without having everything break with the new version.
Its useful if you use the ObsoleteAttribute's override which takes a string:
[Obsolete("Foo is deprecated. Use Bar instead for munging widgets.")]
<frivolous>
Perhaps you could create a TimeBombAttribute:
[TimeBomb(new DateTime(2010,1,1), "Foo will blow up! Better use Bar, or else."]
In your code, reflect for methods with the timebomb attribute and throw KaboomException if they are called after the specified date. That'll make sure that after 1st January 2010 no-one is using the obsolete methods, and you can clean up your API nicely. :)
</frivolous>
As Matt says, the Obsolete attribute is your friend... but whenever you apply it, provide details of how to change calling code. That way you've got a lot better chance of people actually changing. You might also want to consider specifying which version you anticipate removing the method in (probably the next major release).
Of course, you should be diligent in making sure you don't call the obsolete code - particularly in sample code.
Since much of agile development revolves around making something work now and refactoring later if needed
That's not agile. It's cowboy coding disguised under the label of agile.
The ideal is that whatever you complete, is complete, according to whatever Definition of Done you have. Usually the DoD states something along the lines of "feature impelmented, tested and related code refactored". Of course, if you are working on a throwaway prototype, you can have a more relaxed DoD.
API modifications are a difficult beast. If they are only project-internal APIs you are modifying, the best way to go is to refactor early. If you need to change the internal API, just go ahead and change all API clients at the same time. This way the refactoring debt does not grow very large and you don't have to use deprecation.
For published APIs you probably have some source and binary compatibility guarantees you have to maintain, at least until the next major release or so. Marking the old APIs deprecated works while maintaining compatibility. As with internal APIs, you should fix your internal code as soon as possible to not use the deprecated APIs.
Matt's answer is solid advice. I just wanted to mention that intially you probably want to use something along the lines of:
[Obsolete("Please use ... instead ", false)]
Once you have the code ported, change the false to true and the compiler will then treat all the calls to the method as an error.
Watch Josh Bloch's "How to Design a Good API and Why It Matters"
Most important w/r/t deprecation is knowing that "when in doubt, leave it out." Watch the video for clarification, but it has to do with having to support what you provide forever. If you are realistically expecting that API to be reused, you're effectively setting your decisions in stone.
I think API design is a much trickier thing to do in an Agile fashion because you're expecting it to be reused probably in many different ways. You have to worry about breaking others that are dependent on you, and so while it can be done, it's tough to have the right design emerge without getting a quick turnaround from other teams. Of course deprecation is going to help here, but I think YAGNI is a lot better design heuristic when it comes to APIs.
I think deprecation of code is an inevitable byproduct of Agile processes like continuous refactoring and incremental development. So if you end up with deprecated code as you work on your project, that's not necessarily a bad thing--just a fact of life. Of course, you will probably find that, rather than deprecating code, you end up keeping a lot of code but refactoring it into different methods, classes, and so on.
So, bottom line: I wouldn't worry about deprecating code during Agile development. If it served its purpose for a while, you're doing the right thing.
The rule of thumb for API design is to focus on what it does, rather than how it does it. Once you know the end goal, figure out the absolute minimum input you need and use that. Avoid passing your own objects as parameters, pass only data.
Seperate configuration from execution. For exmaple, maybe you have an image encoder/decoder.
Instead of making a call like:
Encoder.Encode( bytes, width, height, compression_type, compression_ratio, palette, etc etc);
Make it
Encoder.setCompressionType(compression_type);
Encoder.setCompressionType(compression_ratio);
etc,etc
Encoder.Encode(bytes, width, height);
That way adding or removing settings is much less likely to break existing implementations.
For deprecation, there's basically 3 types of APIs: internal, external, and public.
Internal is when its only your team working on the code. Deprecating these APIs isn't a big deal. Your team is the only one using it, so they aren't around long, there's pressure to change them, people aren't afraid to change them, and people know how to change them.
External is when its the same code base, but different teams are using it. This might be some common libraries in a large company, or a popular open source library. The point is, people can choose the version of code they compile with. The ease of deprecating an API depends on the size of the organization and how well they communicate. IMO, its the deprecator's job to update old code, rather than mark it deprecated and let warnings fly throughout the code base. Why the deprecator instead of the deprecatee? Because the depcarator is in the know; they know what changed and why.
Those two cases are pretty easy. So long as there is backwards compatibility, you can generally do whatever you'd like, update the clients yourself, or convince the maintainers to do it.
Then there are public api's. These are basically external API's that the clients don't have much control over, such as a web API. These are incredibly hard to update or deprecate. Most won't notice its broken, won't have someone to fix it, won't get notifications that its changing, and will only fix it once its broken (after they've yelled at you for breaking it, over course).
I've had to do the above a few times, and it is such a chore. I think the best you can do is purposefully break it early, wait a bit, and then restore it. You send out the usual warnings and deprecations first, of course, but - trust me - nothing will happen until something breaks.
An idea I've yet to try is to let people register simple apps that run small tests. When you want to do an API update, you run the external tests and contact the affected people.
Another approach to be popular is to have clients depend on (web) services. There are constructs out there that allow you to version your services and allow clients to perform lookups. This adds a lot more moving parts and complexity into the equation, but can be helpful if you are looking at turning over a lot of versions, and having to support multiple versions in production.
This article does a good job of explaining the problem and an approach.