DEV Community: Angelika Cathor

Link Phoenix debug page stack trace to your editor

Angelika Cathor — Sun, 22 Mar 2020 15:57:53 +0000

If you ever worked on a Phoenix app, you might have seen this debug page when an error is raised:

Generating those debug pages when an error happens is a feature turned on by setting config :my_app, MyAppWeb.Endpoint, debug_errors: true, which can be found in config/dev.exs of a freshly-created Phoenix app. It actually comes from Plug.Debugger, not Phoenix itself ^(source).

# phoenixframework/phoenix - lib/phoenix/endpoint.ex#L419-L421
if var!(config)[:debug_errors] do
  use Plug.Debugger,
    otp_app: @otp_app,

Plug.Debugger offers an option to generate links in the stack trace directly to your editor ^(source).

# elixir-plug/plug - lib/plug/debugger.ex#L80-L89
"""
If a `PLUG_EDITOR` environment variable is set, `Plug.Debugger` will
use it to generate links to your text editor. The variable should be
set with `__FILE__` and `__LINE__` placeholders which will be correctly
replaced. For example (with the [TextMate](http://macromates.com) editor):

  txmt://open/?url=file://__FILE__&line=__LINE__

Or, using Visual Studio Code:

  vscode://file/__FILE__:__LINE__
"""

You will need to find out if your editor supports a custom URL scheme that will open files in it. In Plug.Debugger's code, there are examples for TextMate (txmt://open/?url=file://__FILE__&line=__LINE__) and Visual Studio Code (vscode://file/__FILE__:__LINE__).

I personally use RubyMine, which supports the scheme x-mine, which means I can build URLs like this: x-mine://open?file=__FILE__&line=__LINE__.

You can always try out if the custom scheme works for you by trying to open in your browser a link to a file that exists on your machine, e.g. x-mine://open?file=/Users/angelika/.gitignore&line=3

Once you figure out your editor's custom URL scheme and how to pass the file name and line number in that URL, you need to set the environment variable PLUG_EDITOR to that URL. Make sure to use __FILE__ as the file name placeholder and __LINE__ as the line number placeholder.

How to achieve that depends on your operating system and shell. On macOS, using bash as my shell, I needed to add this line to my ~/.bash_profile:

# ~/.bash_profile
export PLUG_EDITOR='x-mine://open?file=__FILE__&line=__LINE__'

Before restarting your Phoenix server to see the results, do not forget to reload the file (. ~/.bash_profile) in an existing shell session or just open a new session.

Result

When I click on the file name in the stack trace, that file opens in RubyMine, on the line that caused the error.

I18n process for a Phoenix app?

Angelika Cathor — Mon, 09 Dec 2019 11:09:42 +0000

I would love to hear about your experiences with translating Phoenix apps. I'm interested both in maintaining an app with many languages, and adding a totally new language to an existing app.

What does the process look like?
Which tools do you use to allow translators work on the translations?
Do you even have dedicated translators?
How do you provide context for the translators so that they know what exactly they're translating? Working in pairs with someone who knows the app, writing descriptions, attaching screenshots? Or are you able to do in-app translations with some JS magic?
Do you use Gettext or something else? Do you use more than one Gettext domain?
How many languages do you have to handle?
What is the biggest pain point of your process?
How do you handle quality assurance of the translations?

Any and all answers will be appreciated!

How to give great code reviews

Angelika Cathor — Sun, 19 May 2019 17:23:24 +0000

This post was initially published on my blog.

To give great code reviews, you need to know why you are doing code reviews.

Why do we review code?

We all know that code reviews are important, but why? They can catch some bugs and prevent terrible design decisions from going to production, but is that their only function?

In my experience, a great code review has three important goals:

Keeping the team up to date with a changing codebase.
Improving the quality of the project.
Providing feedback for the developer.

Keeping up to date with a changing codebase

Giving code reviews forces developers to read the parts of the code that they themselves didn't work on. This improves the team's overall knowledge of the codebase. As a result, task planning goes more smoothly and the accuracy of time/complexity estimations increases.

I. Find out the why first

To be able to understand a code change, you must first understand why it was made.

Most of us work with some kind of issue tracking system. Identify the issue/ticket associated with this code change and read it thoroughly, including the comments. Read the description of the pull request if there is any. This will give you context necessary not only to understand the changes themselves, but to judge if the changes fit the requirements.

Without context, for example, hardcoding a dot as the decimal separator for numbers seems reasonable for your US-only app, but if you read the ticket, you would know that your company is expanding to other countries and now the user's locale needs to be involved in choosing the decimal separator.

If there is no issue/ticket, and no PR description, write down a description of your own and include it as part of the review. If you misunderstood the purpose, the reviewee is likely to point that out.

II. Read, don't skim

Don't be content with a simple "looks good to me". All well-formatted code looks good when you skim it! You want to read the changes and really understand them. Yes, it's difficult. Yes, it will take more time. Yes, it's worth it. It will also increase your chances of catching not-so-obvious project quality issues.

Improving project quality

Having a second pair of eyes look at the code before it goes to production is a good way to catch some bugs and ensure the code will be maintainable.

III. Always run the code

One-line change? Run the code. Just CSS changes? Run the code. Just translations? RUN. THE. CODE.

Do not kid yourself into thinking that everyone always compiles and runs the project after every change they make. We should... but we don't. You know, those times when you have just 5 minutes left before you need to leave the office, and you have just one more trivial change to make, but you don't have the time to verify it.

Ensuring that the project still compiles and runs without throwing exceptions is the least you can do as a reviewer. It's a simple sanity check. So you should do it.

If there were any user-visible changes introduced, make sure you see them with your own eyes. Click through the new UI components.

Run the tests. Yes, I know the CI is supposed to do that. But maybe there are flaky tests that will pass on CI by chance? Or maybe there is a bug that only appears on your macOS, but the CI is running Linux? Maybe somebody didn't follow the correct naming pattern for the test file and the test runner ignored the file altogether?

Do the changes include database migrations? End your review process by rolling them back, checking out master and checking if the project still runs.

IV. Do not nitpick

Somebody inserted two empty lines where they were only supposed to insert one? Don't mention it. The reviewee's patience to fix problems that you have with their code is limited and you don't want to waste it on trivial issues.

Instead, try to find an automated solution that is going to ensure all those trivial details are detected automatically and suggest that your team starts using it.

V. Focus on readability issues that can't be detected automatically

Once you have your automated tools validating function name length and proper indentation, you can focus on the important stuff that only a human can catch.

Do those function/variable names make sense to you? Do they use the project's vocabulary consistently? Could they be confusing? Are there any ambiguous abbreviations?

Fun story: I once spent 10 minutes believing that the app I was working on had a feature where guest users (non-paying users invited by paying users with subscriptions) are allowed to invite more guest users because somebody named a variable sub_guest instead of subscription_guest.

Providing feedback for the developer

Good feedback is feedback that reinforces somebody's good habits, and helps notice and remove bad habits. For your feedback to have any impact at all, you need to ensure that you are being listened to.

VI. Always say something nice

I don't care how trivial the code changes are. You can always say something positive. The more specific the positive feedback is, the better.

It might be hard to come up with something if you never did this before, so here are some generic examples for inspiration:

Good job! I tried my best to find bugs in your code, but couldn't.

Thanks for fixing that typo, I wasn't aware this is the correct spelling of that word.

I love how you named this function. It's immediately obvious what it does.

Wow, that's neat. I wasn't aware of this feature of our programming language / this framework / this library.

I like that you added all of this new code in a new file. It was tempting to put it in the existing file, but that would make the existing file way too big.

If you are afraid to sound silly for appreciating trivial things, ask yourself how you feel when you receive a code review. Are you excited? Or are you dreading it because you know that in the best case, it will be neutral silent approval, but in the worst case, it will be full of harsh criticism? Do you really want your coworkers to dread receiving reviews from you just because you are afraid of sounding silly?

Another important role of positive feedback is that it makes the reviewee more open to your negative feedback.

Do you have that one family member that uses every chance they see you to complain about you? You gained weight again, your sibling makes more money than you do, and you should smile more... How likely are you to actually consider their complaints as valid points that will inspire you to improve yourself? Not at all? Well, receiving only negative feedback from the same coworker for months feels the same.

VII. Avoid judgemental and bossy language

The easiest way to stop sounding judgemental and bossy is to assume you are wrong, and the reviewee is right. Then ask questions that will help you realize why you are wrong. After all, they probably spent much more time working on this code than you spent on reviewing it. They are more likely to understand the details.

Do not say "~~don't do this, do that~~". You don't want to cultivate in your coworkers the ability to follow orders. You want them to think creatively and critically. Besides, nobody likes to be bossed around.

Instead, say "what would you think about...". Signal that you are open to a conversation. People are more motivated to do something if they were involved in making the decision.

Do not say "~~why don't you just...~~". This phrase suggests that your solution is the obvious choice and the reviewee is stupid for not using it. It might trigger a defensive reaction that will make otherwise smart and reasonable people passionately defend a flawed position.

Instead, say "have you considered...?", explain why your solution would be advantageous in this situation and follow up with a friendly invitation to prove you wrong, e.g. "...or did I miss something?".

Now, I am not saying you are actually always wrong. But you are definitely not always right. This approach will make it easier for both you and the reviewee to admit when either of you is wrong without losing face.

GitHub PR reviews

GitHub has a feature that allows you to mark your pull request review as comment, accept, or request changes.

I tend to avoid requesting changes unless I am absolutely certain something needs to be changed. Requesting changes is bossy language and doesn't leave much room for debate. I will make comment reviews until all my questions have been addressed, and then accept.

Summary

Great code reviews take time to do, but they will improve not only your project but your knowledge of the project and your relationship with your team.

Remember:

Keeping up to date with a changing codebase
- I. Find out the why first
- II. Read, don't skim
Improving project quality
- III. Always run the code
- IV. Do not nitpick
- V. Focus on readability issues that can't be detected automatically
Providing feedback for the developer
- VI. Always say something nice
- VII. Avoid judgemental and bossy language

Working less than 40h a week?

Angelika Cathor — Mon, 22 Oct 2018 10:09:13 +0000

Do you work less than 40h a week as a regular employee (not a freelancer)?

Most of us are familiar with the craziness around hiring experienced developers. We can't fill empty spots on our own teams, and constantly receive a sea of spam on LinkedIn.

Some companies go out of their way to lure people. Fancy offices with kicker tables, free fruits, cereal, sweets, sometimes even a company car, and of course higher and higher salaries.

But what if I don't want more money, but more free time?

How realistic it is to ask for a shorter working day, let's say, 6h a day? Or maybe a shorter week, 8h a day, but Fridays off?

I don't have any children or sick relatives I need to take care of, I just want to enjoy life a bit more.

Does anyone here have such an arrangement on a regular employment contract? If yes, in which part of the World?

What my bathroom window taught me about code quality

Angelika Cathor — Sun, 06 Aug 2017 19:28:22 +0000

This post was initially published on my blog.

When my boyfriend moved into our current apartment, he realized there is a small flaw in the bathroom - only the bottom part of the window was made from frosted glass. The top half was crystal clear and would expose everything that happens in the bathroom to the neighbors on upper floors.

He needed to cover the window to have some privacy.

The proper solutions to covering a window are curtains, shutters, roller blinds, or frosted window film. The first three have the advantage of having two states, the window can be either covered or uncovered without dismantling the thing, but they also block the sunlight. The last one covers the window all the time but lets the sunlight in.

All of them require planning and money, and are not doable on a single evening, especially when the shops had already closed for the day.

My boyfriend needed to take a shower in that bathroom that evening.

His solution - tape a piece of cardboard to the window.

Almost a year later, that window is still covered by the same piece of cardboard. Why? Because it was the solution with the highest ratio of value to cost.

It was quick and cheap. The required materials, tape and cardboard, were already in the apartment.
It is effective. It completely stops the neighbors from seeing what they should not see.
It is not a problem that the cardboard stops sunlight. The bathroom already gets plenty of sunlight from the bottom window.
It is not a problem that the window cannot be easily covered and uncovered without tearing down the cardboard. The window is too high to reach without a ladder.
It is not a problem that the cardboard is ugly. We do not really care.
There are no young and impressionable interior designers coming over to our apartment, looking at that window and thinking that a cardboard stuck to the window is a good design pattern.

So... what's the point?

This is just a silly example, but it made me think about how I approach the quality of the code I write and the code I expect from others.

I suffer from perfectionism. My coworkers complain that I can be too demanding of them (but also of myself). Sometimes I catch myself being really stubborn during a code review (sincere apologies to everyone that was ever affected). If that happens, I try to stop and ask myself - what is this code for?

The value of the code is the usability it brings to the user, not its cleanliness or beauty.

The price of the code is the time and the energy spent to develop it.

Usually, bad code is expensive. Bad code is hard to understand. Bad code is hard to debug. Bad code is hard to extend. Because of all of these reasons, bad code also decreases the value that can be delivered in the future.

But sometimes, just sometimes, you know you are writing code that will never again be read, and will never be modified. You know it will be used, maybe just once or twice, and then it will be thrown away. That is when bad code is cheap.

I understand now that a good software developer is not somebody who delivers good, clean code all the time, but somebody that is able to assess the situation and deliver a solution with the highest ratio of value to (long-term) cost. Even if that means writing a quick dirty hack once in a while.

Oh, but try to make sure no young and impressionable junior developers will come over to your code base, look at that bad code and think it's a good design pattern since a respected developer like yourself wrote it. Maybe leave a word of warning in a comment?

# Here be dragons!

# Forgive me, Father, for I have sinned...

# ~~~ POLICE LINE DO NOT CROSS ~~~ POLICE LINE DO NOT CROSS ~~~

# I was young and I needed the money.