4 ms·

As with a lot of things, it comes down to communication. Between teams, and between the services they write. Which is just another expression of Conway's Law.

by kitd 7y ago

As with a lot of things, it comes down to communication. Between teams, and between the services they write. Which is just another expression of Conway's Law. IIRC Fred Brooks pointed out that the # of bugs in a system correlates closely with the # of lines of communication within and between the teams. Joshua Bloch recommends in "Effective Java" that, if possible, 3 potential clients should participate in the design of an API, for the same reason. So a well-designed interface or OpenAPI spec is worth its weight in gold. Ofc, "microservices" here means separate running instances available on a network. But monoliths can be "service"-oriented as well. OSGi was good for this in Java, but any system able to load shared objects or plugins dynamically can follow the same pattern. And the benefit is that, if your app hits the jackpot and needs to scale outwards, the service interfaces, ie the lines of communication, are already well-defined. So, service-oriented monolith first, then microservices if needed.

organsnyder 7y ago
> So a well-designed interface or OpenAPI spec is worth its weight in gold. When I worked on a SOA team, I tried to begin any new effort (whether a new API or modification to existing API) solely discussing the API contract. It was (ideally) high-level enough that business analysts and project managers would understand it, and it helped to guide us away from getting mired in implementation discussions too early. At that organization, we rarely had the opportunity to involve multiple customers at the same time during design discussions (we were typically engaged to help a specific consumer implement a specific feature), but the institutional memory in the SOA team helped us to keep in mind existing/potential other users of each particular webservice.
- hinkley 7y ago
  The last place I worked that split the devs into UI and backend teams was in a sort of slapstick comedy situation. Nothing ever shipped on time because the front end and backend could never quite talk to each other or needed elaborate conversations to do the simplest of things. This was our new flagship project, I got consolidated in from another team and ended up as a lead not long after. We had been doing some UML modeling, sequence diagrams during planning, and still having this problem, so rather than repeating the same action and expecting a different outcome I started trying to flip the script. What ended up working was not code diagrams but data flow diagrams and sequences. To get X you need Y, and to derive Z you need A, B, and X. To publish you need all five. After that, the APIs mostly wrote themselves, we reordered a few different forms, but most importantly variance dropped like a rock.
  - username3 7y ago
    Can you share examples of your data flow diagrams? Do any open source projects share these documents?
    - hinkley 7y ago
      Mostly these were white boarded, but essentially I/we would draw a collaboration diagram (although I could have sworn these used to be called something else). They showed what data was needed to make certain decisions (eg, a conditional drop down that is populated based on another piece of data, or complex validation steps) and where to get data that already existed.
      - dionian 7y ago
        activity diagram?
        hinkley 7y ago
        Yeah it looks like the activity diagram was substantially altered in UML 2.0. What we called an activity diagram then looks more like a collaboration diagram now.
    - Terr_ 7y ago
      Aside, take a look at tools like PlantUML as a way to create your diagrams. It's higher-level than, say, rolling everything with Graphviz, while easier to share and edit than a bunch of PowerPoint/Visio/etc. files. The great thing about generated-diagrams is that you can easily store and version the original text representation along with the code it describes or applies to. https://plantuml.com/ https://plantuml.com/
beh9540 7y ago
> As with a lot of things, it comes down to communication. Between teams, and between the services they write. Which is just another expression of Conway's Law. This is so accurate. I've heard engineers give state not needing to communicate, chillingly, as a positive for microservices, like "we won't need to talk to each other if all of us are working on different services". My other favorite is using microservices as an excuse for why the product isn't working "oh, my service is working fine, but his service is doing this when it shouldn't", when we're on a small engineering team.
- dllthomas 7y ago
  I think there's an element of truth to the engineers' claims. Working on different code bases means there are a lot of things you would otherwise need to talk about that now you don't. It's very much the case that you still need your interfaces to be clear (in fact, clearer!) but those discussions can be somewhat isolated, so more work can proceed asynchronously. Just how isolated depends on how exact (and correct) the specifications are, which is a question of trading up-front work against interruption.
- afarrell 7y ago
  > not needing to communicate sighhhhhhhhh API documentation is a medium of communication as much as any user interface. If you don't keep this in mind, then using your service's application programming interface will be a bad experience.

by kitd 7y ago

organsnyder 7y ago

> So a well-designed interface or OpenAPI spec is worth its weight in gold. When I worked on a SOA team, I tried to begin any new effort (whether a new API or modification to existing API) solely discussing the API contract. It was (ideally) high-level enough that business analysts and project managers would understand it, and it helped to guide us away from getting mired in implementation discussions too early. At that organization, we rarely had the opportunity to involve multiple customers at the same time during design discussions (we were typically engaged to help a specific consumer implement a specific feature), but the institutional memory in the SOA team helped us to keep in mind existing/potential other users of each particular webservice.

hinkley 7y ago
The last place I worked that split the devs into UI and backend teams was in a sort of slapstick comedy situation. Nothing ever shipped on time because the front end and backend could never quite talk to each other or needed elaborate conversations to do the simplest of things. This was our new flagship project, I got consolidated in from another team and ended up as a lead not long after. We had been doing some UML modeling, sequence diagrams during planning, and still having this problem, so rather than repeating the same action and expecting a different outcome I started trying to flip the script. What ended up working was not code diagrams but data flow diagrams and sequences. To get X you need Y, and to derive Z you need A, B, and X. To publish you need all five. After that, the APIs mostly wrote themselves, we reordered a few different forms, but most importantly variance dropped like a rock.
- username3 7y ago
  Can you share examples of your data flow diagrams? Do any open source projects share these documents?
  - hinkley 7y ago
    Mostly these were white boarded, but essentially I/we would draw a collaboration diagram (although I could have sworn these used to be called something else). They showed what data was needed to make certain decisions (eg, a conditional drop down that is populated based on another piece of data, or complex validation steps) and where to get data that already existed.
    - dionian 7y ago
      activity diagram?
      - hinkley 7y ago
        Yeah it looks like the activity diagram was substantially altered in UML 2.0. What we called an activity diagram then looks more like a collaboration diagram now.
  - Terr_ 7y ago
    Aside, take a look at tools like PlantUML as a way to create your diagrams. It's higher-level than, say, rolling everything with Graphviz, while easier to share and edit than a bunch of PowerPoint/Visio/etc. files. The great thing about generated-diagrams is that you can easily store and version the original text representation along with the code it describes or applies to. https://plantuml.com/ https://plantuml.com/

beh9540 7y ago

> As with a lot of things, it comes down to communication. Between teams, and between the services they write. Which is just another expression of Conway's Law. This is so accurate. I've heard engineers give state not needing to communicate, chillingly, as a positive for microservices, like "we won't need to talk to each other if all of us are working on different services". My other favorite is using microservices as an excuse for why the product isn't working "oh, my service is working fine, but his service is doing this when it shouldn't", when we're on a small engineering team.

dllthomas 7y ago
I think there's an element of truth to the engineers' claims. Working on different code bases means there are a lot of things you would otherwise need to talk about that now you don't. It's very much the case that you still need your interfaces to be clear (in fact, clearer!) but those discussions can be somewhat isolated, so more work can proceed asynchronously. Just how isolated depends on how exact (and correct) the specifications are, which is a question of trading up-front work against interruption.
afarrell 7y ago
> not needing to communicate sighhhhhhhhh API documentation is a medium of communication as much as any user interface. If you don't keep this in mind, then using your service's application programming interface will be a bad experience.