Elixir reading code patterns 📚

[carlogilmar]

Reading patterns

Hello dear community! I’d like to share some ideas and asking for your experience.

During my lasts years working as a contractor using Elixir I’ve been in almost the same scenario during the onboarding:

• A huge code base with many contributors
• Many complex documentation (mix of technical and business stuff)

So my conclusion is that as developer you need a good toolbox with communication practices (enough communication to ask for help to your team) and also technical practices that allows you to understand a project in the best way by yourself.

Git versions control

One of that practices is git version control, I remember a project where all my coworkers were in different timezones that mine, so I felt really alone with the project.

So I had the idea to explore the commits in the project, but the scenario for me was explore the PRs merged, so in this way I could be able to read the ticket, understand the scenario, and then read the code solution to complement my understanding about how my team is developing software.

Some years after discover the power of this practice I could give a talk at the Git Merge conference about this Commit driven development

Collaboration by PRs

Also I usually use the GitHub workflow to integrate code, so this could have many opinions, but for me as Mexican one of the biggest gaps is the language, it’s not easy for me communicate in english, fortunately I could develop my visual communication through Visual Thinking, and this makes me feel confortable explaining my ideas in my team, so when I’m creating a new PR I like to try to sketch my solution with many details possible.

So I’m really really really interesting on explain software by visuals, I know there are a lot of tools to create fancy diagrams (UML, C4, D2 language, mermaid, etc), but for me it’s not enough to communicate all the ideas in a simple way, I think this is the key, be able to communicate something complex in something really simple to understand.

So I use to create this kind of sketches using Visual Thinking practices and I had really good results. I think this is not a replacement of a case diagram or any other diagram, it’s another complement, because a C4 diagram as the example could have a deeply detail on some context but there is still a big level of complexity, in my opinion, to understand the diagram.

Reading code

So trying to deep on this topics (also I love teaching about tech concepts so I’m interesting on the learning side) I found really good resources.

One of them is The Brain’s Programmers, this is interesting to me because the autor mentions why read code matters, and associate this activity to how our brain works through cognitive processes involving long-term memory, short term-memory and the working memory. So she explains how can we understand design patterns for develop software but also as a cognitive charge more practical to be processed by our brains. She mentions how the iconic memory help us to read and understand code, so then we can organize code in a way easy to be processed in our iconic memory. I strongly recommend this resource and the bibliography to all people interested.

So when I read this I felt excited because I think visual thinking works in that way, you can build illustrations to facilitate the understanding about something complex. I know, it’s a really big big big topic.

Reading code patterns

So now I’m trying to sketch how elixir developers use to explore new code bases, I know there are many diagrams that we can use to understand a project (entity-relationship diagram, dependency graph) and also for BEAM systems we have all the diagrams to explain processes interactions, but I need to understand by the beginning.

So after put all my ideas on the table, when I use to explore a new project I use to:

1. Read the module backbone: I mean see what public and private functions contains.
2. Functions for data transformation: One approach I love in functional programming is data transformation, so I use to sketch a function in terms of inputs and outputs. This help me to understand part of the flow.
3. Function usage: I use to search where a function is called to see module dependencies.
4. Function skeleton: Understand a function in terms of the functions called inside.

I think this are the most simple practices that are helpful for me to understand code and for explain code in PR’s. Of course there should be more. My goal is be able to model this patterns and create a tool focused in dev experience to help developers to understand elixir code bases by generate significant sketches.

So, what are your read patterns? I’d be really happy and excited to read all your feedback on this

Thanks for reading, Carlo.

[dhony]

Hello @carlogilmar. First of all, I’m a huge fan of your work. It has been a while I’m following you on Twitter and appreciating your drawings.

@carlogilmar

So I had the idea to explore the commits in the project, but the scenario for me was explore the PRs merged, so in this way I could be able to read the ticket, understand the scenario, and then read the code solution to complement my understanding about how my team is developing software.

Sometimes I started to follow a Open Source repository on GitHub, tracking all the issues, PR and conversations around it. The last one was the Plausible Analitycs. I’ve learned a lot tracking the PRs, reading the comments, code reviews and understand how the team came up with solutions. It’s good to see how great engineers work together sharing their experience, sharpening the codebase.

Also, I would mention that I read a lot of documentation but I only undertand it when I draw multiple sketches. It is kind of teaching myself how things works under the hood.

[al2o3cr]

Late reply here, but I also find myself doing the reverse kinds of processes - usually when debugging a mysterious failure.

In those scenarios the start point is some error message like invalid foo in bar, which if you’re lucky is explicitly written someplace in the code.

From there I trace backwards - “what code calls this function?” - with two goals in mind:

• where did things go off-track? Sometimes the error message is only the visible result of a much earlier problem

• how did we get here at all? As a consultant I find myself troubleshooting in codebases that I’m barely familiar with, but this process helps narrow the focus from “understand everything” to “understand this specific code path”