Communicating in Code

Writing elegant code is an extremely difficult task. In some sense, you can think of it as writing a paper in a mix of foreign languages and trying to make sure that your Spanish professor and your Mandarin professor can both read it in their native tongue. If this sounds like a difficult task, that's because it is. In our example, the Spanish professor may be your computer (or compiler or interpreter or whatever), while your Mandarin professor is likely your colleagues.

The point that I'm trying to make is that humans process things differently (and less predictably) than computers. However, when you're writing code, you're usually writing under the premise that two different entities will consume that code. One of those entities is a computer and the other entity is one or more humans. Most of the time that second entity is your colleagues or other maintainers of that code, but sometimes it may just be you. These two separate entities have very different expectations around how code is processed. It's often difficult to write code that is easily understood by the computer but also understood by humans.

A mutual, shared context helps create the same level of understanding across multiple contributors in a codebase. A really great example of this can be found by comparing two technologies built for frontend web interfaces. The first being Angular and the second being React. Angular is a full-on framework for building Client Side web applications where React is a library for building reactive user interfaces. Angular has a lot of opinions on how the entire application fits together where React is more of a toolkit that you can build your own framework (or choose not to) on top of. Because of this, Angular often takes longer to learn (and is more complex because there's many more parts). My experience agrees with that. Angular took me longer to learn, but when working on our Angular codebase the entire development team had a strong understanding of what needed to be done and how the framework enabled that work. Working in React with team members across varying skill levels and opinions has shown a fair amount of friction when trying to answer questions that Angular answers for us. Sure, it's more to learn up front but when the framework provides that mutual, shared context, it's easier to keep everyone on the same page. People on the same page have a lot less that they need to communicate via code because they call fall back to the opinions and tools of the framework.

Design Patterns provide you with a way to express application architecture decisions in a way that makes sense to most contributors. Additionally, Design Patterns still have meaning to the computer as well. A great example of a design pattern can be seen when building an application that talks to multiple databases. You can leverage the Adapter Pattern to build a Database Adapter. This helps remove the need to identify which database you're working with (and which flavor of SQL or NoSQL) and instead, consumers can directly communicate with the adapter. This form of abstraction generally is considered helpful, but layering pattern on top of pattern can often make things feel more complex, too. If you're interested in learning more about Design Patterns, I'd recommend this book.

As I mentioned in the last paragraph, Design Patterns help express application architecture. Similarly, you can take your design patterns and place them in an application architecture diagram to show how the pieces of your application fit together. If the diagram is messy, something is possibly wrong with the pattern choices that were made and you may want to revisit those patterns. Alternatively, when designing a new application, start with application architecture diagram to identify patterns that would help, then implement those in code afterwards.

Comments provide insight into code but are completely ignored by the computer. These are most useful when you have to explain why a choice was made ("https:// we're using a for loop here instead of map because the performance really matters"). You can think of comments as a way to provide information for the human-party but keep in mind that the compiler or interpreter will ignore them. You can even use a comment to beg forgiveness from your peers, too! ??

I say that comments are ignored by the computer, but that's not entirely true. Some compilers will look for specially formatted comments to generate documentation for your code. There are tools out there that take this a step further. OpenAPI (the artist formerly known as "Swagger") helps generate documentation for your entire API using the OpenAPI specification. This means that, if you write your comments correctly, you can generate your own API specification that another developer can use a tool to parse, which in turn will generate a client for them to use to interact with your API.

Hot Off The Press: Spicy Tech ??

Prisma is an extremely interesting piece of tech to me. Prisma is a typesafe ORM for NodeJS applications. Prisma works with MySQL, SQLServer, Postgres, and SQLite. The heart of Prisma is the Prisma Schema which defines your application models and their relations (with an emphasis on being human readable). If you already have an existing database, you can use Prisma Introspect to generate a Prisma schema for the schema you already have in place! Additionally, Prisma has support for migrations and a GUI client if that's your thing (Prisma Studio). If you're looking to use an ORM in Node, I strongly recommend checking this one out!

Little Bits:

• Bosun 0.1.0 released - Support for generating help text with flags added!
• Flutter 2.8 released - Performance improvements out the wazoo!
• Educative.io is a fun little way to learn with course quality instructions but all via text. I struggle a lot with certain video courses and this has been a pleasant alternative for me!

Wanna get your own Little Bit shared? Tell me here!