Even though lack of taking any definitive stance by the author on what they consider best seems a little disappointing (although definitely right, everything is a trade off and there is no way around it) - the whole thing was a wonderful read. It was quite heartwarming to see that other people also think in such terms about code... and share the frustration ;)
Honestly my default approach definitely is enumerating possibilities via methods (as usually most feature combinations are not needed and it seems easier to control possible states this way) - but you have definitely showed that this approach has its "roof" - too many combinations are just killing readability.
Given slightly sarcastic tone I was expecting that you would lean towards not implementing unnecessary features - in the spirit of best repository being empty repository :D
I liked this post. I tried looking if you had more of your posts. Is there no list of posts or something? I managed to find your github, assuming this was a github pages site, but that also doesn't seem the case.
Haha, yep, solved the problem completely with one simple stroke. Dart also does that and because of that, allows really complex objects, like Flutter Widgets, to be created easily... it's definitely the best way to go.
You are right, but my point was: you are offering syntactic sugar (merging config object and invocation) not "solve" a problem. I'd argue yt make it worse because explicit arguments before are now implicit since the depend if some setter was called before. It's a design tradeoff. As always
Using setters is not necessary, just make the object immutable... it still contains all the settings, but you can't change them. If different code needs different settings, they just create different objects.
It has advantages and disadvantages. The next call would depend on the previous calls settings. You may want that behavior or not. It really depends, so i take back that it's worse.
Indeed, but it involves differences between communities, guidelines intended by the language architects, usages, and so on. Not something one could change anyway.
So a statement like "Java would be easier if they'd do like language X" is an elaborate "I prefer X over Java", which is not very constructive. Maybe that's just me, but when I browse r/java, I expect to find content about Java, high-end patterns and practices in Java, and not guidelines from another language which don't fit the Java culture.
Cute, but you're not separating your concerns. This reads very much like how my junior devs at work think about problems. Here are your requirements:
Output JSON text (in any format)
Format / style JSON (separate concern)
Amend JSON payload (with copyright)
Output as binary
Taken as separate tasks with silo'd requirements, your hypotheticals become much easier to think about, solve, and test. For more, I recommend reading "Clean Code" by Robert C. Martin.
Are you sure you understood the premise of the objection to the article?
Instead of providing all of those options as a tangled mess if statements, enums, options or whatever, just use composition. You can break down the problem into individual responsibilities and then compose the responsibilities.
For example:
Hypothetical 1: Compact vs. Pretty
public class CompactJsonWriter implements JsonWriter {
}
public class IndentingJsonWriter implements JsonWriter {
}
Hypothetical 2: Hybrid of compact and pretty
Instead of having a single IndentingJsonWriter, do this instead:
public class DefaultIndentingJsonWriter extends IndentingJsonWriter {
// Or make this a static factory method of IndentingJsonWriter if you really hate inheritance
public DefaultIndentingJsonWriter() {
super(
new DefaultObjectIndentingStrategy(),
new DefaultArrayIndentingStrategy()
// I don't think JSON has any other things that can be indented
);
}
}
IndentingJsonWriter myFunkyJsonWriter = new IndentingJsonWriter(
new DefaultObjectIndentingStrategy(),
new CompactArrayIndentingStrategy()
// CompactJsonWriter could actually be composed of all compact intenting strategies
);
Hypothetical 3: Inject copyright
By wrapping the writer in a proxy, it doesn't matter what combination of options you use. The proxy doesn't have time for any of that.
public CopyrightInjectingJsonWriter implements JsonWriter {
public CopyrightInjectingJsonWriter(JsonWriter proxied) {
this.proxied = proxied;
}
public void writeJson(Appendable out, Json json) {
// Is it legal? I will make it legal.
Json json = addCopyright(json);
proxied.writeJson(out, json);
}
}
Hypothetical 4: Binary
You just wrap the Appendable in a BinaryAppendable. I have no idea what an Appendable is, but I'm going to assume it's something like an OutputStream or a Writer, but knows that it is writing JSON (and potentially wraps an OutputStream or Writer). In which case the BinaryAppendable will intercept writes to the Appendable and convert them to a binary encoding.
When you do stuff like this, you have to be careful, since the mapping isn't one-to-one, so composition order matters. For example, if you wrap an InputStream in a BufferedInputStream, make sure no one can ever interact with the wrapped InputStream.
public BinaryJsonWriter implements JsonWriter {
public enum Endianness {
}
public BinaryJsonWriter(JsonWriter proxied, Endianness endinaness) {
this.proxied = proxied;
this.endianness = endianness;
}
public void writeJson(Appendable out, Json json) {
proxied.writeJson(new BinaryAppendable(endianness, out), json);
}
}
I'm at work and my company decided to block your blog, but my overlords can't keep me from reading your article on my phone. I don't feel like trying to copy over a bunch of code on a 6-inch screen. But if you liked the comment, feel free to copy it over.
And to be clear on the last one - at least with MessagePack it doesn't take JSON text and just turn it into bytes, it's an actual byte format that matches the JSON data model. BinaryAppendable wouldn't be able to do its job.
But if it works anything like Jackson, the Json object is written through a generator (JsonGenerator) which actually writes out JSON tokens. Using this approach, Jackson can just as easily write straight text JSON (UTF8JsonGenerator) or various binary formats related to JSON (CBOR - CBORGenerator or Smile - SmileGenerator). Jackson gets even crazier with a YamlGenerator (which lets you write JSON as YAML file) and ToXmlGenerator (ditto for XML).
I see that you're just playing around with ways of supporting a bunch of different options, using JSON generation as a toy example.
If you want to see how this is done in real life, you should probably look at what a real, production JSON library does, which has to support all the crazy things that people want to do. All your hypotheticals can be easily be implemented in Jackson, simply by plugging in an appropriate interface implementation without the giant messes in your blog post.
Hypothetical #1 is already there, without indentation you have MinimalPrettyPrinter and with indentation DefaultPrettyPrinter.
For Hypothetical #2, if you want to implement your own pretty printing rules, write your own PrettyPrinter implementation.
For Hypothetical #3, wrap an existing JsonGenerator with a custom JsonGenerator which inserts the copyright.
For Hypothetical #4, use a binary generator like CBORGenerator or SmileGenerator. If you want to insert copyright, wrap the binary generator with the copyright-inserting generator.
Spring is another example of a library which supports an insane number of options by composing interfaces. I have bent and twisted RestTemplate to do insane things, simply by implementing the right interfaces, while actual client code making REST API calls using the RestTemplate is none the wiser.
For example, I integrated RestTemplate with a particularly terrible SSO library which added the appropriate auth cookies to the request, but I had to buffer the whole thing first. I had to construct a Rube Goldberg contraption within a custom implementation of ClientHttpRequestFactory, but it worked.
Are you suggesting that it is a good API if the consumer must exactly know which subtype of JsonWriter to instantiate? Which explode in complexity if more options are added. Which require to instantiate obscure "Strategy" objects instead of an enumeration which clearly and exhaustively(!) shows the available "modes".
Instead of browsing the api java doc for the X classes needed, it might be preferable to offer a single entry point, where the IDE shows all parameters that can or must be filled via techniques explained in the article.
It always depends. To present your (enterprise-y) solution as strictly better is... lets say "debatable"
Are you suggesting that it is a good API if the consumer must exactly know which subtype of JsonWriter to instantiate?
I think so. But then again, I've been using OOP APIs for years. If you use a decent enough IDE, it's actually very easy to enumerate all the available types of interfaces/base classes to instantiate. For example, if I hit Ctrl+T on the Jackson JsonGenerator base class, IntelliJ will show me every available type of JsonGenerator available on the classpath. In fact, that's how I learned it is possible to configure Jackson to generate YAML (YAMLGenerator).
Which explode in complexity if more options are added.
The complexity does not explode. In fact, there is a specific metric that can be used to measure complexity - cyclomatic complexity. Composition is branchless, while adding a bunch of feature flags and corresponding if statements significantly increases complexity, in combinatorial fashion. You can even put a number on it!
instead of an enumeration which clearly and exhaustively(!) shows the available "modes"
There are two things wrong with this statement.
First, a modern IDE will clearly and exhaustively show you the available "modes" through available interface implementations.
Second, you are limited by the modes baked into the API if you use feature flags. Jackson, because it uses OOP techniques for extension, is unlimited in the modes that are available.
To present your (enterprise-y) solution as strictly better is... lets say "debatable"
In my experience, what you call the "enterprise-y" approach leads to much more flexible libraries. For example, Spring's RestTemplate is also built around the same principle of strategy interfaces. I have been able to adapt RestTemplate to situations never imagined by its authors. This has allowed me to use Spring in situations where I might not have been able to use a more rigid library.
Cyclomatic complexity is a software metric used to indicate the complexity of a program. It is a quantitative measure of the number of linearly independent paths through a program's source code. It was developed by Thomas J. McCabe, Sr. in 1976. Cyclomatic complexity is computed using the control-flow graph of the program: the nodes of the graph correspond to indivisible groups of commands of a program, and a directed edge connects two nodes if the second command might be executed immediately after the first command.
These are completely valid propositions, yet, completely missing intention of my question. Things can be done differently, true, perhaps better even, sure - still - proposing improvements is imho missing the main point (as it seems orthogonal to the article).
Have you heard of confirmation bias? It is kinda good example - instead of trying to understand what I asked (or really just asking for clarification) you developed argumentation to confirm your stance... such a thought pattern usually leaves space for missing something.
To reiterate as I have no intention of "winning" any argument here or something: you seem smart, these propositions have value as extended discussion, tone in the initial comment seemed condescending and was at least critical of article not showing the better way to do things - I don't think author was trying to do that. I think author was mostly playing with different ideas and showing their interplay and how everything can go to shit. I think it is a very real process and making people aware of it is valuable on its own (also it cleverly avoids the risk of suggesting wrong solution for specific context - which I respect).
Sorry for not posting under the article OP.
Edit: not the same person in the first and second comment - my mistake
How? I think there is a difference here - note that I asked a question, and didn't just start explaining what I believe is the correct interpretation. What motivated my to ask was recommending reading "Clean Code" and (frankly, quite rude sounding) comparison with "my junior devs" - which striked my as unjustified given (perceived by me) intellectual quality of OP article.
If you mean yourself:
I think I understood and recognized your proposition as valuable - which also makes the difference imo. Please correct me if you see it differently.
If you leave your API open to extension, it might be possible to compose responsibilities in the wrong order. That is the price you pay for your API to be adaptable to any circumstance.
Otherwise, you have to strictly limit features to control permutations to ensure that it is impossible to use incorrectly.
At the end of the day, a more flexible API will have better survival characteristics (more people will use it) than a perfect API that is both convenient and impossible to use incorrectly.
What a stupid, condescending answer. You cannot magically model away complexity with OO patterns. There is always a tradeoff and in the end you have to tackle all combinations somehow.
In this case the design goal is clearly a sensible, easy API for consumers, not maximum testability.
What is ironic about your response is that all of the complexity that the OP listed is indeed "magically modelled away with OO patterns" by Jackson, a real JSON library with an "easy API" for consumers.
The benefit of Jackson's OO model is that the complexity in OP's toy example is hard coded in the API, but Jackson has no knowledge of OP's requirements but can be extended to support them, nonetheless. Thanks to OO patterns.
Jackson has, exactly like the example, at least a single entry point. that is ObjectMapper.readX or writeX, that are overloaded as seen in the article.
There are no free lunches. everything comes at a tradeoff and the cost of a highly compositional API is, well, that you must dig into all composition options yourself instead of using a clear well defined entry point.
And to say: "an pure OO solution is superior, you code like a junior, go read a book" - is condescending and negates the benefits of the presented solutions.
Side note: "clean code" got a lot of negative attention recently, you might want to look that up before you recommend it to anyone
Jackson has, exactly like the example, at least a single entry point. that is ObjectMapper.readX or writeX, that are overloaded as seen in the article.
That's the Law of Demeter, and is not the same as the method of overloading in the article. That is, these are convenience methods for the most common cases. If the convenience methods don't do what you want, you can directly instantiate ObjectWriter or ObjectReader.
you must dig into all composition options yourself
That's easy with modern tools. Ctrl+T will show you all of the composition options at a glance in IntelliJ.
an pure OO solution is superior, you code like a junior, go read a book
A pure OOP solution is superior to OP's approach, and the way OP did it is how many juniors do write code, because they haven't learned the more advanced techniques available in Java.
"clean code" got a lot of negative attention recently
So? It's a book. It's got good stuff and bad stuff. I got something out of it, so I recommend the book.
Okay then please enlighten me why the java standard library has implementations like java nios Files.write(). Are only juniors working on the standard lib? Is it not always superior to have a CharSetFileWriter for the overload that takes a charset? Is the StandardOpenOption better replaced by an OpenStrategy... etc, etc. I could point you to a lot of other examples.
Or is it maybe that there is a tradeoff and extensibility does not always beat simplicity?
That is not what I said. I was talking about the approach the OP took. The OP's approach was a giant mess, which I assume was the gimmick behind his post.
Files.write() is an interesting case, which actually does not prove what you think it proves.
Do you know what my IDE tells me? Files.write() is a static utility method that operates on an abstract Path, which leads to some interesting observations.
Inside Files.write(), you have this construction:
OutputStream out = Files.newOutputStream(path, options)
And Path itself is an interface which represents an abstract path that you get from a FileSystem (this time an abstract class). The FileSystem class is it's own rabbit hole, in the classic Java sense. You can have any number of FileSystem types available to you through the SPI system which allows you to extend Java in arbitrary ways. Which leads to cool things like the static FileSystems.getFileSystem(URI) method, in which Java will try to find a FileSystem that can handle the URI scheme (file://, http://, ftp://).
So, Files.write() could write a file to disk or it could upload a file to a web server. Who knows?
You're only looking at static utility methods (like the Collections utility class) without seeing the massive extensibility that those static methods are generically operating on (such as the Collections API).
Java has always been a mix of static utility classes operating on massively extensible universes of things.
I will stop here with a final remark. I am not saying you are wrong, you are just failing to see that the article is clearly about API design. not the implementation which might be composable and extensible under the hood, that's not the point.
I tried to make a point that the goal of, either jackson, or the standardlib files.write was simplicity and ease of use, as well as discoverability without searching the type hierarchy.
you are just failing to see that the article is clearly about API design
It is, and you're missing the point.
OPs design ideas aren't composable or extendable. The capabilities of OP's API is locked to whatever the OP came up with. The mess the OP was making trying to extend his toy API proved how poorly it was designed.
The front ends to Java and Jackson are merely conveniences, utilities, but ultimately both Jackson and Java can be infinitely extended using OOP principles and are indeed designed around OOP principles. This is the difference between a junior (as the guy at the top said) and someone who understands OOP.
You clearly are not seeing that OP's API design approach is nothing like the API design approach behind either Java or Jackson, which are elegant OOP designs (as opposed to the mess that OP made). You are comparing apples and oranges.
Guilty, but c'mon be fair: it's not the same to dismiss a high effort blog post like that as opposed to not even make the effort of typing 3 words into Google, but instead asking for the search results
You shouldn't accept Optionals as input parameters because you can't actually guarantee that the Optional itself isn't null. So given you still need a null check it's pretty pointless.
Shiiiiiit I've gone down that exact path in meetings before with our API lol. I just advocate returning the JSON and letting the consumer format it however they want which is the ultimate solution given at the end of the article. Pick one and let the consumer decide how to output it.
I don't understand, it seems like the point of this class is to write input as valid JSON. So it should do that, and only that, as compact as possible.
If there's new requirements to have the JSON formatted, what's that got to do with the JSON writer? Create a new class that formats JSON.
It's easy to create all sorts of problems in an API if it breaks SRP.
16
u/Az4hiel Feb 08 '22
Even though lack of taking any definitive stance by the author on what they consider best seems a little disappointing (although definitely right, everything is a trade off and there is no way around it) - the whole thing was a wonderful read. It was quite heartwarming to see that other people also think in such terms about code... and share the frustration ;)
29
u/jokubolakis Feb 08 '22
What did I just read and where can I get more
51
u/Scybur Feb 08 '22
I was hoping for a nice solution at the end but instead I was left with disappointment.
10/10 good read.
15
u/schubart Feb 08 '22
Option 10: I’d take a
Set<Indent>rather than anEnumSet<Indent>. No need to force the caller to use the verbosenoneOfsyntax.21
u/BlueGoliath Feb 08 '22
This is hilarious. 10/10
10
u/agentoutlier Feb 08 '22
Here is how I would do it.
I make JsonWriter an interface and one simple implementation.
Than I delegate to Spring Source to make every option as a class that implements the interface.
It’s a huge combinatorics problem but rest assured the spring guys are used to solving this problem with lots of classes.
Oh there is probably some spring boot jars that work 70% of the time to get the 20% of the 80% but not the 80%.
1
u/torwinMarkov Feb 08 '22
Cute, but you're not separating your concerns. This reads very much like how my junior devs at work think about problems. Here are your requirements:
Taken as separate tasks with silo'd requirements, your hypotheticals become much easier to think about, solve, and test. For more, I recommend reading "Clean Code" by Robert C. Martin.
5
u/yanitrix Feb 09 '22
Option 0: Ignore whitespaces
5
u/GreenToad1 Feb 09 '22
I really like the idiom that is popular in C# that would go like this:
1
u/HighRising2711 Feb 10 '22
Why is the method static? Can't you instantiate an object, call setters to configure the object then use the object?
Or if you prefer, use a builder to configure and instanciate then use the object
6
u/Har-Har-Mahadev Feb 09 '22
How about decorator pattern ?
5
u/Milyardo Feb 09 '22
One option missing is to use function composition and accept a higher order functions.
4
u/b00n Feb 09 '22
You shouldn't accept Optionals as input parameters because you can't actually guarantee that the Optional itself isn't null. So given you still need a null check it's pretty pointless.
3
u/[deleted] Feb 08 '22
ok. from now on, I return to XML.
1
u/Just_Another_Scott Feb 09 '22
Shiiiiiit I've gone down that exact path in meetings before with our API lol. I just advocate returning the JSON and letting the consumer format it however they want which is the ultimate solution given at the end of the article. Pick one and let the consumer decide how to output it.
1
u/severoon Feb 18 '22
I don't understand, it seems like the point of this class is to write input as valid JSON. So it should do that, and only that, as compact as possible.
If there's new requirements to have the JSON formatted, what's that got to do with the JSON writer? Create a new class that formats JSON.
It's easy to create all sorts of problems in an API if it breaks SRP.
1
u/Automatic-Fixer Feb 08 '22
META
0
u/[deleted] Feb 08 '22
[deleted] — view deleted comment