Zig open interfaces issues

The vibe is that zig will not have native dynamic dispatch support.

That said, there are a few niggles to close out:

• What is the standard pattern for doing that sort of thing?
• Will comptime ducktyping be improved?

SBE Repeating Group Gotchas

SBE is the fastest off-the-shelf way to serialize data.

To help support that, it really prefers you to use fixed length fields. If you need an unknown number of submessages, it's a littler harder...

1. There is very little documentation in general, and for repeating groups it's incomplete. A big omission: you must always explicitly decode every member of every repeating group, in the same order as they are defined in your schema. If you do not do this, your results could be mysteriously corrupted. Alternatively, you could explicitly "skip" the ones you are not interested in, with the relatively new sbeSkip() call. E.g.
   

          
           weWantSerialNumber(carDecoder.serialNumber());
           weWantModelYear(carDecoder.modelYear());
           FuelFiguresDecoder fuelFigures = fuelFigures(); //we don't want fuelfigures

           if (fuelFigures.count() > 0)                    //but if it was encoded...

           {                                               //we must iterate over it anyway

               while (fuelFigures.hasNext())

               {

                   fuelFigures.next();

                   fuelFigures.sbeSkip();

               }

           }
   

           PerformanceFiguresDecoder performanceFigures = performanceFigures();

           if (performanceFigures.count() > 0)

           {

               while (performanceFigures.hasNext())

               {

                   performanceFigures.next();

                   weWantOctaneRating(performanceFigures.octaneRating());
                   performanceFigures.sbeSkip(); //actually needed in the sample

               }                                 //because there's a nested repeating group!

           }
   
   

2. If you're working with code that does not use repeating groups, and you add one, lots of things might break unexpectedly. Because wrapping a decoder with an incorrect blockLength will mostly work if you don't need to decode repeating groups or variable length data fields. You need to use the blockLength on a header message, which in turn needs to be the BLOCK_LENGTH of the encoder. This excludes the length of the repeating groups. On the bright side, nowadays there are wrapAndApplyHeader() convenience methods on both the encoder and decoder objects. 
3. If you want to read repeating groups from the same decoder more than once, you need to call sbeRewind().
4. There's currently a bug in which toString can break repeating groups

Bookmarks and Full Text Search

Bookmarks suck. They don't have to.

They suck because they don't actually work for their primary use cases:

1. where did I read about that cool thing X? 

2. where was that cool article about Y that I didn't have to time to read, but would like to read now?

Heck, at some point I found it easier to google for pages instead of trying to find them in my bookmarks. 

Other use cases should be handled slightly differently:

3. "Bookmarks Bar", "Pin a tab", and "Save a shortcut" features are all useful for commonly-used pages or web apps.

4. "Manage Search Engines" feature is useful for sites that you want to search often.

4. I'll bet Chrome soon adds support for saving tab groups, which will be useful for gathering lots of pages for a particular project, e.g. a bibliography.

Practically speaking, labels and categorization are annoying to add, and don't really help find things later. The titles that maintainers give to web pages are also often unhelpful for retrieval.

The solution is automatic full text search of all bookmarked pages.

That way, you can retrieve a page by anything that you see on the page, without any additional organizational work.

On a Mac, you can get already get this via Spotlight and print with "Save to PDF", though there's some user interaction involved.

Worldbrain's Memex supports full text search of bookmarks well, and for free. I have mixed feelings about it. On the one hand, this feature is implemented by an open source plugin, and the maintainers support local first software. On the other hand, they have a much bigger vision, and it's unclear how much they want to support the free part of it. It currently sports a non-dismissible reddish prompt to register for the cloud support.

Probably I'm Dunning Krugering, but it just doesn't seem like that difficult of a feature to implement. And it feels like a core service. I wonder how Apple and Google might decide to take on a feature like this. There's no reason to end on a low note. If you don't care about sync-ing across your devices, go ahead and install free Memex on your PC, and on your tablet!

iPhone Shul Shush

 Now it's finally possible to silence iPhones in shul (or church or whatever)!

1. Settings / Focus / Do Not Disturb / Add Schedule or Automation / Location
2. enter something to identify your shul, e.g. part of the name
3. select the right one
4. touch Done

Woo!

Now if only there were a way to automatically prompt people to do this when they arrive, using something like airdrop. "This location wants you to be in Do Not Disturb. Is that alright? Yes - silence notifications here, No - continue to notify me and don't ask again, I Don't Know - ask me next time I visit"

Vim plugin idea

When working with verbose logs, you want to suppress uninteresting lines.

So, wouldn't it be cool if you could select two lines, and vim would hide all lines that are similar to them.

1237 boring is blah, all good

1238 boring is foo, all good

1238 WARNING

1240 boring is blah, again

When the user selects the first two lines above, vim would hide lines matching the pattern \d+ boring is \w+, all good.

It'd need the ability to unhide the next or previous line.

We could also get fancy, and support generalizing previous patterns. In the example above, you could later choose the fourth line, and vim would amend the previous pattern to \d+ boring is \w+, [ a-z]*. We'd have to document some decisions about how general to be, e.g. it's not obvious above that we should use \d+ instead of 123\d.

Closest existing thing I could find: https://www.vim.org/scripts/script.php?script_id=2302

Scrolling two files curmudgeonry

It's useful to be able to synchronize scrolling through two files, especially for comparing two files that have too many intraline differences.

Vim supports this, with this annoying incantation:

vim -O oneFile anotherFile -c "windo set scrollbind" -c "windo set scrollopt+=hor" -c "windo set nowrap" -c "windo set cursorbind"

Switch between the windows with: ctrl-w ctrl-w

Nowrap is useful because otherwise different sized lines don't display nicely.

Other annoying things: 

• The documentation can't decide what this feature is called, scroll binding or scrolling synchronously.
• Gvim doesn't seem to support cursorbind.

Though maybe vimdiff is actually better for most similar use cases. It gets the defaults right, and with gvim it seems to get cursorbind right too.

Toki Pona

Toki Pona is a supremely simple constructed language. It's a real Newspeak (from Orwell's 1984), but for good and not evil.

It's very cool. Unfortunately nobody seems to seriously use it for international collaboration. (Apparently this is called auxlang, and obviously English right now is it.)

I was initially grumpy about the "pre-verb" part of speech, but now I believe it's consistent with the general rule that a word modifies its preceding word. For example, a noun precedes its adjectives, and a verb precedes its adverb. So: mi ken pali ==  I can work. mi wile e ken pali == I want the ability to work.

Nullaway @Initializer

Nullaway is the currently most practical solution to the billion dollar mistake.

Its @Initializer annotation is one of its practical features; if an object is not expected to be used until one of its methods in executed, that method can be annotated. Then fields can still be statically guaranteed to be non-null if they are initialized in that method, even if they are not initialized earlier.

Nullaway does not, however, statically guarantee that @Initializer methods are actually executed. Therefore, it's better to initialize non-nullable fields in a constructor.

Poor Man's Projectional Editing

Projectional Editing is programming that goes beyond simple text entry. Notable projects are Lamdu and Jetbrain's MPS and to some extent Intellij itself.

Historically, programmers have been reluctant to stray too far from textual programming. A good compromise approach is to represent language features both textually and graphically. For example, the exponents in LegibleMathematics are both superscripted and ^ prefixed.

We could support the property of always keeping the program valid, and still give the feel of textual editing:

1. as the user types, insert code to make the program valid
   e.g. if the user types if, then we'll insert (true) {}
   
   
2. in the inserted code, automatically select the next bit that isn't forced, to clarify that it will be replaced as the user types
   e.g. in the case of inserted (true) {}, we'll select the (true)
   
   
3. in general, whenever the user types the same thing as the next required bit, just advance the insertion point over it
   e.g. in some existing code if (x) { y(); } the user clicks before the semicolon and types ; }, we won't change anything at all, and just advance the insertion point to after the }
   
   If we want to support whitespace, then we could change the traversed text to use the new whitespace that the user types.

The above behavior enables the user to just obliviously type brand new code and have it work like in a traditional editor.

The third point is inspired by Parinfer, and Parinfer also has an idea for editing existing code. Inserting a brace somewhere automatically removes the following brace, and removing a brace will insert one as late as possible. e.g.

void f() {
    if (foo) {

        bar();

        baz();

    }
    qux();
    quux();

}

Removing the } after baz() will automatically insert one after quux().

Inserting } after bar() will automatically remove the other } in the function.

Of course we want tab completion, and once we have that and the above, we don't have to worry about intermediate invalid edits. In languages with stronger types than java, it could be that there isn't necessarily any automatically choosable value, in which case we'd have to use typed holes. In mainstream languages, we could use null at the worst.

It's nice to default to a value that causes the new code to essentially be an identity function, e.g. if the user types + then we'll append 0. If the user types * then we'll append 1. But of course this isn't always possible.

Changing a symbol usage changes just that one usage. Changing a symbol at its definition (or initialization in python for example), instead refactors the symbol and renames all of its usages. Changing a signature to remove parameters just updates all usages to not supply those parameters. Changing a signature to add parameters updates all usages to supply a default value as above.

Lastly, with this approach we can be very clever about cut & paste. A "cut" which would involve an invalid program is no trouble; when the "paste" comes, we can do the appropriate refactoring. In the example function above, if the user cuts the baz() call, and pastes it outside the function, we can automatically change the code to:

void f() {

    if (foo) {

        bar();

        g();

    }

    qux();

    quux();

}

void g() {

    baz();

}

And of course select the new function name g so that it can be easily changed. And some pastes would be illegal, e.g. pasting qux(); quux() in place of foo.

So, this "always valid" approach is very nice for refactoring. Its main benefit however is to enable powerful live coding, e.g. devcards.

Git gotcha

Since the rise of github, most teams build software using a pull request workflow. Therefore the local "master" branch is a bit of a gotcha. You can commit to it, but that will only ever cause you grief. That is, you'll forget about those commits, and they'll eventually cause a conflict, and you'll get something mysteriously broken when you just want "master". Fix it with this:

       
            git branch -D master
            git branch master origin/master
       
 

And actually consider not having a local master at all, and always using origin/master instead.

Watches making sure you're "up"

Smart watch alarms used for waking up in the morning should have a feature: sound until standup!

That is, you can configure a alarm to continue playing or vibrating until the watch detects that you are standing up (using barometer, accelerometer, gyroscope or whatever). Obviously all other easy ways to turn off the alarm would have to be disabled.

IPython replacing shell

IPython is a good UNIX shell replacement, for those who want an interactive shell with a better programming language.

You can use unadorned shell commands, file globbing, and pipes, as well as regular python.

Regular shell: ls *.py | grep -v foo

Regular python: for x in range(3): print(x)

There is special syntax for running shell commands to be easily used by python code...

Shell in python: my_python_var1 = !ls #only for assigning variables

Python in shell: ls $my_python_var2

For anybody pining for python2: print "foo" #works!

Also works for any outermost python function: dir enumerate(list())

But unfortunately doesn't currently work with other code: for x in range(3): print x

For some reason, the maintainers are no longer publishing a profile for this stuff, so you can use the following to get up and running:

pip install ipython

mkdir -p ~/.ipython/profile_default
cat >> ~/.ipython/profile_default/ipython_config.py <<EOF
from IPython.terminal.prompts import Prompts, Token
import os

class MyPrompt(Prompts):
    def cwd(self):
        cwd = os.getcwd()
        if cwd.startswith(os.environ['HOME']):
            cwd = cwd.replace(os.environ['HOME'], '~')
            cwd_list = cwd.split('/')
            for i,v in enumerate(cwd_list):
                if i not in (1,len(cwd_list)-1): #not last and first after ~
                    cwd_list[i] = cwd_list[i][0] #abbreviate
            cwd = '/'.join(cwd_list)
        return cwd

    def in_prompt_tokens(self, cli=None):
        return [
                (Token.Prompt, 'In ['),
                (Token.PromptNum, str(self.shell.execution_count)),
                (Token.Prompt, '] '),
                (Token, self.cwd()),
                (Token.Prompt, ': ')]

c.TerminalInteractiveShell.prompts_class = MyPrompt
c.TerminalInteractiveShell.editing_mode = 'vi'
c.InteractiveShell.autocall = 2 #insert parens around functions as much as possible
c.InteractiveShellApp.exec_lines = ['%rehashx']

EOF

Select and Lookup

Select

Computers let you select something you see and do useful things with it. This interaction should be improved and standardized.

Whether it's with a mouse or a finger, when you select text, a little menu should pop up, and its first choices should be: Lookup, Copy, Share.

It's fine if applications want to customize and support additional choices, but those three should always be the first choices. Currently each application has those mixed up differently with other choices, sometimes not visible without an additional action, and sometimes even missing them entirely.

Just like on mobile devices, the menu should pop up immediately on traditional computers without needing a separate action like a right click. That the menu should not interfere with changing the selection.

Lookup

"Lookup" should be customizable, in terms of whether the first screen is a local search, a query to a popular search engine, a dictionary lookup, etc. Other forms of lookup should be linked from that first screen.

For example, selecting the word "customizable" above could show the content of the Wikipedia page for "customizable", with links on the first page there to the dictionary entry, to the Google search, and to the Memex page.

Ideally the first screen would display the page returned by Google's "I'm Feeling Lucky" feature. As the linked page mentions, making this feature more prominent might have revenue implications for Google. As long as we're talking about Google, we should also mention that Google already tries to implement something like what I'm describing. So many Google searches have a dictionary definition and a wikipedia link in their first pages. That would be redundant if operating systems were already presenting that information even more prominently.

Another important possibility for the main lookup page, when the selected text is a hyperlink, would be the actual linked page. For example, the two pages linked above are a lot more useful for understanding how I'm using the terms of the linked text than any of the other sources of information discussed here (at least the time of writing), so should be the primary destination for readers looking them up.

Automated tests and new bugs

Can unit tests find unexpected bugs?

Russ Cox offhandedly mentions that, no, unit tests only "make sure bugs you fix are not reintroduced over time", in his brilliant recent piece on versioning in go.

On the other hand, Hillel Wayne has a nice example using property based testing and contracts. See if you can spot the bug yourself before following that link:

def mode(l):
  max = None
  count = {}
  for x in l:
    if x not in count:
      count[x] = 0
    count[x] += 1
    if not max or count[x] > count[max]:
      max = x
  return max

Hillel analyzes several different approaches to testing. The punch line is that you catch the bug with the following steps:

• annotate the mode function with its specification:

  
  @ensure("result must occur at least as frequently as any member", 
    lambda a, r: all((a.l.count(r) >= a.l.count(x) for x in a.l)))
  
  

• also prepend the following:

  
  from hypothesis import given
  from hypothesis.strategies import lists, integers, text
  from dpcontracts import require, ensure
  
  @given(lists(text()))
  def test_mode(l):
      mode(l)
  
  

• install the prerequisites with: pip3 install hypothesis dpcontracts pytest
• run pytest on the file that you created with the mode function and its test code

Though this particular specification looks like an alternate implementation, it isn't intended to be. Using one implementation to test another is a kind of "test oracle", but that doesn't feel like an elegant way to find bugs. The test implementation could have its own bugs, and if maintained by the same programmers, it could even have the same bugs as the regular implementation.

In contrast, a specification can be easier to read than any practical implementation. At least with current technology, there are limits on how clear pragmatic code can be. Specification-like code can be too slow. Perhaps the specification could be an oversimplified implementation, and still be useful for testing.

Testing based purely on the specification is not enough however. We need some automated equivalent of "clear box testing".

Zig

It'd be great for Zig to replace C/C++.

Zig's main advantage over C is robustness. That includes features like:

• better error handling
• optional instead of null pointers
• undefined behavior handling, either at compile time or configurably

It aims to keep all of the advantages of C, including:

• no magic
• seamless interoperability
• similar reach, via LLVM

Its main architectural trick is good support for compile-time code execution. This is even how it implements generic types.

It also includes (or will include) tooling that's as good any platform's:

• build
• cross compilation
• test
• format code
• package and share (TBD)

Beyond Literate Programming

Programs must be written for people to read, and only incidentally for machines to execute.

― Harold Abelson

More important to read a program than to run it? Absurd! How can something even be a called a program if it can't be executed by a machine? So soften the hyperbole: programs should first be written to be easy to read, and only afterwards optimized. It's the opposite of premature optimization.

The quote's hyperbole is good, because technical debt is caused by customers benefiting only directly from machines executing programs, as opposed to anything associated with people reading programs' source code. All maintenance programming starts with people reading. So this could be a programming principle that's more important than extensibility, discoverability, clean code, clean architecture, SOLID, DRY, YAGNI, KISS, least astonishment, defensive programming, offensive programming, cohesion&coherence, consistent style, information hiding, and good separation of concerns. Let's call it the readability principle: programs should be written in such a way as to communicate their function as clearly as possible. "Function" refers to function which is meaningful to the user. "Communicate" refers to informing somebody who is not already familiar with the program, and not even an expert in all of the technologies employed. This implies that programmers should avoid both Rube Goldberg machines and fancy language features.

Knuth's literate programming is the original push to have a single program provide both function and documentation. Its most popular descendant is the Javadoc family, which is now the standard way to document APIs. Jupyter Notebooks and Devcards publish executable documentation. Concordion brings together test code and documentation in a lovely way. All of these involve additional program documentation, which is not itself executable. Of course this should not distract from making properly self-documenting code. All additional documentation must have clear and agreed benefit, to justify the cost of manually keeping it up-to-date with the program itself.

The next big thing in program readability is humble: put design documents and technical specifications in the same repository as your program! And favor the markdown format. The best new source control repositories (Github, Bitbucket, and Gitlab) all render it automatically to the web. Having program and doc together makes it easier to keep them in the sync. Versions and links are easier, as well as running find-and-replace across program and doc. Perhaps most importantly, if you keep program and documentation together, you signal that programmers should maintain both.

Simplicity

In programming conversation, people often incorrectly use the word "simple" as a synonym for "good". This is probably because they have on some level internalized the lesson that "complexity kills", so they conflate "simplicity" and "justified complexity".

Simplicity refers to having fewer layers, fewer features, fewer moving parts, and fewer distinctions.

Translating objects simply

How do you translate one object into a different, related object? Simply!

interface FooBarTranslator {

    Foo translate(Bar bar);

}

Some people, when confronted with this problem, think "I know, I'll use a framework." Now they have two problems, as the saying goes.

Many people code it themselves using abstractions and design patterns. Their code has organizing principles, but it isn't clear what those principles achieve. This code starts out as interesting to read, and gets progressively worse as each new developer touches it. It's even harder to maintain when we're integrating with other systems. It's a pain to test properly with those other systems, so we're reluctant to change the code unless we're forced to.

So here's a simple pattern to use the next time you find yourself translating objects.

1. Use a single function with a single line for each field on the object to which you are translating.
2. Whenever you need something new, do the simplest thing that could possibly work.
3. There is no step 3!

Before any more explanation, let's do an example or two...

E.g. if Foo has fields a and b and c, your translator might look like:

    Foo translate(Bar bar) {

        Foo foo = new Foo();

        foo.setA(bar.getQux());

        foo.setB(bar.getBaz());
        foo.setC(bar.getQux());

        return foo;

    }

Here's an example that shows simple ways to address multiple aspects of the problem.

    Foo translate(Bar bar) {

        Foo foo = fooFactory.create();

        foo.setA(123);
        foo.setB(bar.getB()+1);

        foo.setC(aFunction(bar.getC()));

        D d = anExpensiveFunction(bar.getD());
        foo.setD(d.getSomePart());
        foo.setE(d.getSomeOtherPart());
        foo.setNestedF(fBarTranslator.translate(bar));
        if (bar.getFloat() != null) foo.setPrimitiveFloat(bar.getFloat());

        return foo;

    } 

Organizing the code in terms of the target object eliminates a whole category of bugs and confusion, in which the responsibility for setting a single field is spread out over multiple places. The code in those different places grows overlapping and conflicting behavior.

Organizing the code in terms of the target object achieves some "functional programming" goodness. Stakeholders often ask questions like "why does this field have this value? where does it come from?" and our code makes it easy to answer that kind of question. Each of the lines in the translation function is like a definition of the target object field. Though a single field on the source object might contribute to the value of multiple fields on the target object, a single field on the target object is only ever determined by a single complete function.

For fields with nontrivial logic, that logic should reside in a function in a different class, a la Single Responsibility Pattern. (I favor static methods for pure logic and field injection for logic that needs to consult some state, but there are good reasons to do otherwise.)

Any additional architecture only ever harms your code! Resist the temptation to add architecture. It will not pay for itself.

An important rule that you can't see in the examples above: never retrieve information from the target while you are translating to it. Another thing that might not be obvious: if your translation is a nice normal stateless translation, then your translator class should not have any member variables. Use local variables and not member variables for your expensive calculations.

If you have more than a handful of fields, you might want to order your setter calls alphabetically. That makes it harder for developers to accidentally set the same field twice in the same function. It makes it easy to find a field on a printout or to consult multiple fields without having to search via the app. It also makes git merge conflicts smarter; you want a conflict when two different developers merge different code for setting the same field, but you don't want a conflict when two different developers merge code for setting two different new fields. Just adding support for new fields to the end of the function yields a conflict in both cases.

Adding support for new fields to the end of the function is not a guideline which is easy to defend, or which is even easy for faithful developers to see in the code. If that's your de facto organizing principle, then you'll end up with no organizing principle. In contrast, if you alphabetize and have clear standards around dependency injection etc as mentioned above, you'll have one canonical simplest possible program for any translation. One right way to do it.

This raises the biggest disadvantage. If you don't have firsthand, repeated, experience with the pain of the alternatives at scale, you might not appreciate this pattern. 😉

The Web is a detail?

Should programs be mostly independent of how they communicate with each other?

Yes, if you can do it right.

If you do it wrong, you'll end up with a big hunk of useless complexity. You have been warned. The rest of this post describes one way of "doing it right" in Java. TL;DR use Autovalue and Mapstruct in a separate module.

One of the nicest things about Java is that it allows checking your interfaces at compile time, before running any of your code. So you can have one module that depends on the interfaces of your transport technology, and another module that doesn't. You can even have Maven prevent people from accidentally spreading that dependency.

This enables building and testing the domain code entirely independently of transport technology choice. Ideally, you could add support for another transport later by adding another module and not making any changes to your domain code. If your transport technology involves code generation, you might keep the generated Data Transfer Objects (DTOs) in the same module as your adapter code.

If you need multiple transports from day one, then this architecture is obviously the right way to go. It's more controversial if you're starting with a single transport, and it's also easier to get wrong. There's a strong argument to be made that you aren't going to need it. Besides being disciplined about dependencies, the most important thing is to keep the adapter layer small. We can do that with some open source code generation tools...

Let's say that you have a bunch of DTOs to work with messages that are sent and received by your message encoding technology, e.g. Google Protocol Buffers (Protobuf). Instead of working with those technology specific objects directly, your domain code can work with corresponding lightweight value objects.

Initially, you'll want to have one abstract class corresponding to each Protobuf message. With a little bit of annotation, AutoValue will nicely generate value objects for you, as well as fluent builders to compensate for Java's lack of named parameters. Here's an example, assuming you have a FooRequest message with fields bar and baz:

@AutoValue
abstract class FooRequest {
 abstract int getBar();
 abstract String getBaz();

 Builder builder() { return new AutoValue_FooRequest.Builder(); }

 @AutoValue.Builder
 static abstract class Builder {
  abstract Builder setBar(int i);
  abstract Builder setBaz(String s);
  abstract FooRequest build();
 }
}

That goes in your domain module, and your domain code can proudly rely on it. Imagine a similar FooResponse. For example, you might have a FooUseCase with a method that accepts a FooRequest. E.g.
@Singleton
class FooUseCase {
 FooResponse handle(FooRequest r) {
  someFunction(r.getFoo(), r.getBar());
  return FooResponse.builder()
   .setBar(...)
   .setBaz(...)
   .build();
 }
 ...
}

To map between the DTO and the domain object, use the following Mapstruct annotated abstract class in the adapter module:

@Singleton
abstract class FooUseCaseAdapter {
 FooRequestMapper requestMapper = new FooUseCaseAdapter$FooRequestMapperImpl(); //generated by mapstruct
 FooResponseMapper responseMapper = new FooUseCaseAdapter$FooResponseMapperImpl(); //generated by mapstruct
 @Inject FooUseCase foo;
 @Inject Sender sender;

 void handle(FooIncomingMessage m) {
  sender.send(responseMapper.map(foo.handle(requestMapper.map(m)));
 }

 @Mapper(unmappedTargetPolicy=ERROR, unmappedSourcePolicy=IGNORE)
 static abstract class FooRequestMapper {
  FooRequest map(FooIncomingMessage m);
 }

 @Mapper(unmappedTargetPolicy=IGNORE, unmappedSourcePolicy=ERROR)
 static abstract class FooResponseMapper {
  FooOutgoingMessage map(FooResponse r);
 }
}

Using Mapstruct means that you don't have to write adapter code for each field. If you have a field of the same name in the DTO class and in the Autovalue class, the generated code will map that field automatically. The "unmapped" policy of ERROR means that you will be stopped at compile time from accidentally renaming a field in the DTO but not in the domain, or vice versa. It also prevents you from forgetting to add a field to the DTO when you add a field to the domain. You'll want to use the "target" and "source" as above, lest you get lots of false positives as people evolve the DTOs independently of your application.

So our YAGNI overhead is two trivial classes for each DTO. One of them needs two lines for each DTO field used by the application. Considering that the application needs changes anyway to use a new field, those two extra changes do not seem onerous. Besides not having to write and maintain the generated code, there's the advantage that its design doesn't drift. The Autovalue classes may accumulate logic, via interfaces and default values, for example. That's perfectly fine.

This whole exercise assumes that most of your automated tests will be on the Autovalue classes. The unmapped error policy reduces the risk of bugs, even if you don't test the DTO mapping at all, but the paranoid among us might want to have a test or two to exercise each field. Mapstruct is smart enough to map between different types, so that you can use an long integer on your DTO and an Instant in your domain, for example. If you use that feature, it makes sense to test it.

What about generated enum types? Perhaps compromise is best here: generate or pull the enum classes into a separate module, and as long as these don't do strange things in static initialization, just rely on that module in the domain. The opportunity for coupling related to enums should be small. The alternative is to duplicate all the enums manually. Though Mapstruct will automatically map and warn regarding those too, that overhead may not pay for itself, especially for enums that have values that the application just needs to pass on without special handling.

Notice in the example above that a single adapter handles publishing as well as incoming message processing. We could have the domain code return a tuple-like object which contains references to Autovalue objects for all of the messages which could be published in reaction to the incoming message. This is very easy to test, and doesn't require any mocking at all. Alternatively, we could instead have the domain call some kind of publisher interface, with two implementations: a mock implementation for testing, as well as an adapter of the real transport. The real implementation would be bound to the interfaces using a dependency injection configuration in the adapter. This approach enables the adapters to be quite uniform, and to hardly ever change. If the number of possible messages to publish for each case is small, the first approach is simpler.

(The name of this post is a quote from Bob Martin. How the database might also be a detail is a topic for another post. Event sourcing makes it less relevant.)

State

Computer programming is much more difficult than it should be. It's much less elegant than it should be. Programs often resemble logical Rube Goldberg machines, or corporate income tax forms.

This complexity is caused by our inability to properly manage "state", or information that changes over time. Procedural programming, object oriented programming, domain driven design, immutable data structures, and monads are all attempts to better manage state, and none of them are good enough.

The more recent functional reactive technologies are a step in the right direction. React is good, and MobX, Javelin, and Matrix are better. Serious programming can be as easy as spreadsheets. We can have full referential transparency, and we can refactor without fear.