DEV Community: Guilherme Ferreira

Embedding dotnet format in your development cycle

Guilherme Ferreira — Fri, 11 Feb 2022 00:00:00 +0000

I have to confess. I've spent more time than acceptable during code reviews, looking into C# code formatting issues. It's such dumb work. I should focus on other things rather than watching if a colleague forgot to format the code or if someone is using a different editor with different rules.

That's one thing that that I miss when writing C# in Visual Studio if I compare it to writing JS in Visual Studio Code. It's so beautiful when Prettier auto-format when I save the file. You define rules in your .editorconfig and BOOOM! 💥 No more nitpicking on indentation or whitespaces. You can even enforce other rules like having the System using directives first.

# .editorconfig Example
# Organize using directives
dotnet_sort_system_directives_first = true
dotnet_separate_import_directive_groups = false

And now we can bring the same experience with dotnet format!

.NET CLI has introduced a new command to format. "dotnet format" was an existing dotnet tool, but now (.NET 6.x SDK and later versions) it's integrated into the CLI. You install the CLI, and you have it.

How can I use it?

It is a simple command-line tool, so you can integrate it into your CI/CD toolchain.

One interesting "dotnet format" option is to verify if changes should be performed with --verify-no-changes. Besides that, you can include only some files in the verification with --include.

dotnet format --verify-no-changes --include src\Infrastructure\CustomerRepository.cs

So, those two arguments are perfect for a CI pipeline.
Every time a PR (Pull Request) is open, you can verify any broken format rule during build time.

Runing dotnet format with GitHub Actions

You can run it in your prefered build system, being TeamCity, Jenkins, Azure DevOps, etc., but here I will use GitHub Actions.

The process is quite simple. If you go to GitHub Actions Marketplace, you will find some extensions to run dotnet format. I will be using "xt0rted/dotnet-format" by Brian Surowiec.

So, I added a step to my workflow:

- name: Run dotnet format
      uses: xt0rted/dotnet-format@v1
      with:
        only-changed-files: "true"

The workflow:

name: .NET

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2
      - name: Setup .NET
        uses: actions/setup-dotnet@v1
        with:
          dotnet-version: 6.0.x

      - name: Run dotnet format
        uses: xt0rted/dotnet-format@v1
        with:
          only-changed-files: "true"

      - name: Restore dependencies
        run: dotnet restore
      - name: Build
        run: dotnet build --no-restore
      - name: Test
        run: dotnet test --no-build --verbosity normal

Now, when a PR is open, dotnet format will run to check the changed files. If someone edits a file without formatting, the build will fail.

That is pretty cool, but I would prefer to prevent build attempts because somebody forgot to format a file.

dotnet format and Git Hooks

So, how can I prevent commits if I forget to format the code?

The answer to that is Git Hooks.
Git gives you a way to hook in some git steps. So, you can run your code on pre-commit.

You can do that in many ways (see here), but I prefer to use "pre-commit". Pre-commit simplifies your process and offers you an easy way to adopt new hooks. Go take a look. It's pretty cool!

How to configure pre-commit

First, you need to install pre-commit (see here).

After installed, create a file ".pre-commit-config.yaml" in the root folder.

Add the following snippet there.

repos:
  - repo: https://github.com/dotnet/format
    rev: ""
    hooks:
      - id: dotnet-format
        args: [--folder, --include]

Now, install your git hook script:

pre-commit install

After this, dotnet format will run every time you git commit! 😍

Wrapping up

Obviously, one of your teammates may not install "pre-commit" and keep editing files with Sublime, Vim or Notepad 🤷. That's why is important to do it not only as a pre-commit but also as part of the build. One works as a Guard and the other as a feedback cycle improver.

It's quite a simple process, so it's worth trying.

I hope that this was useful! To get more tips like this, follow me on Twitter (@gsferreira) and let's keep in touch!

Looking into C# Property Patterns Performance

Guilherme Ferreira — Thu, 03 Feb 2022 00:00:00 +0000

Property Patterns is one of those things that rapidly changed how I write code. I love how the code looks clear and expressive (see what I've written about it here).

In that spirit, I recently tweeted and posted to LinkedIn how I loved simple things like implementing a Guard Clause on collections. See the tweet below.

(here)

I was aware that this is not for the taste of everyone, and obviously, most comments were from people that prefer other conventional ways of expressing it.

One of the comments was the usual when you post .NET related content: "What about performance?"

Performance 🚀

So, I decided to go on a journey to understand how performant Guard clauses with Property Patterns can be.

To do that, I decided to compare the multiple suggestions received with my loved Property Patterns.

So, the candidates were:

Option A

if (list is null || !list.Any()) 
    return false;
return true;

Option B

if (list?.Any() == false) 
    return false;
return true;

Option C

if (list == null || list.Length == 0) 
    return false;
return true;

Option D

if (list is not { Length: > 0 }) 
    return false;
return true;

Option E

if (list is null or { Length: 0 }) 
    return false;
return true;

After running a benchmark, I got the following results.

That was an excellent result.

How can they do that? 🤔

As you can see, Property Patterns aren't the most performant, but they are close enough. How?

If you pick option D or E and lower it using SharpLab, you will see that the Property Patterns lowered version is quite close to Option C, the most performant option.

So what? 🙄

Now what? Why should I use Property Patterns when there's a most efficient option?

That is true. On the other hand, Property Patterns are expressive (my opinion), but also they guide you to better decisions.

As an example, you can't use LINQ with Property Patterns. You can see from benchmark results that it is a good constraint to have. Anything that can set you on the path of success is a good thing to do.

After this journey, this is just one more reason to keep using it. I know it may feel strange for an experienced .NET developer, but give it a try.

🔗 You can find the source code used here.

I hope that this was useful! To get more tips like this, follow me on Twitter (@gsferreira) and let's keep in touch!

Taking control over xUnit test names

Guilherme Ferreira — Mon, 24 Jan 2022 00:00:00 +0000

Unit Testing naming conventions are almost as conflicting as spaces versus tabs. I've never worked on a project where everyone has the same preferences.

Often, you even find multiple practices in the same codebase. They go from Given_When_Then to MethodUnderTest_Scenario_ExpectedResult or even variances where one person may use Pascal and another Snake case.

Often, we forget that the most important thing is expressing clearly the test intent. So, it's the question of how to make the most of those shapes or forms.

xUnit Test name customization

The good news is that you have some ways to control xUnit behaviour in terms of test display names.

The simplest one is defining a custom Display Name through the Fact attribute.

[Fact(DisplayName = "Get the max number of an array")]
public void GivenAnArray_WhenApplyMax_ThenGetThenBiggerOne()
{
    new[] { 12, 10, 20, 42 }
        .Max()
        .Should()
        .Be(42);
}

That will give you a higher degree of freedom, but it's an extra effort, difficult to keep consistent across the code. We already need to craft a meaningful method name, so having an extra-label may lead to out of sync text. We already know what happens to code comments. We don't need to deal with the same problem in tests.

So, what can we do?

One interesting thing from xUnit is the configuration files.

There, you can find many options to change the default behaviours of xUnit. One of them is related to Display Name.

xUnit in .net will display names based on class and method name by default. With the configuration file, you can define the display name to be the Method name.

To do it, create a xunit.runner.json file in the xUnit project root, make sure it's included and add the following snippet.

{
  "$schema": "https://xunit.net/schema/current/xunit.runner.schema.json",
  "methodDisplay": "method"
}

To include, add to the csproj:

<ItemGroup>
    <Content Include="xunit.runner.json" CopyToOutputDirectory="PreserveNewest" />
</ItemGroup>

Besides that, the most interesting thing is the method display name options, where you can find options to:

Replace underscores with spaces;
Replace operators with matching symbols (example: eq becomes =);
Replace periods with a comma and a space.

To enable them, go to the xunit.runner.json file and add a new key.

"methodDisplayOptions": "replaceUnderscoreWithSpace,useOperatorMonikers"

So, for the following tests:

public class DisplayNameTests
{
    [Fact]
    public void Given10_WhenMultiplyBy2_ThenGet20()
    {
        var result = 10 * 2;

        result.Should().Be(20);
    }

    [Fact]
    public void Is_20_gt_10()
    {
        20.Should().BeGreaterThan(10);
    }
}

Once you run the tests, you will see:

Instead of:

Wrapping up

I don't say you must use this, but knowing that these features exist may be helpful to improve the readability of your tests when analysing the results. In some cases, the existing conventions may help achieve better results, like if you are using Snake casing, enabling the "replaceUnderscoreWithSpace" is a quick improvement.

Now it's time to take a look into your codebase, look into the existing configuration options, and you may find a quick win.

🔗 You can find the source code used here.

I hope that this was useful! To get more tips like this, follow me on Twitter (@gsferreira) and let's keep in touch!

Expressive C# code with Property Patterns

Guilherme Ferreira — Mon, 20 Dec 2021 00:00:00 +0000

C# has been growing with F# inspired features.

One that is most exciting is Pattern Matching.

The introduction of Pattern matching led to Property Patterns.

Property patterns deserve close attention. Since they were included on C# 8, they have been evolving, with improvements either on C# 9 but also in C# 10.

Property Patterns are interesting ways to make the code more expressive, and in this post, we will see how.

What is a Property Pattern

You use a property pattern to match expression properties to nested patterns.

static bool IsFirstOfTheMonth(DateTime date) => date is { Day: 1 };

So, with Property Patterns, you can go from this:

private static (bool isValid, string reason) Validate(Note note)
{
    if (note == null)
        throw new ArgumentNullException(nameof(note));

    if (note.Title.Length < 5 || note.Title.Length > 50)
        return (false, "Title should be 5 to 50 char long");

    if (note.Content == null) 
        return (false, "Content is required");

    return (true, "");
}

To this:

private static (bool isValid, string reason) Validate(Note note)
    => note switch
    {
        { Title.Length: < 5 or > 50 } => (false, "Title should be 5 to 50 char long"),
        { Content: null } => (false, "Content is required"),
        null => throw new ArgumentNullException(nameof(note)),
        _ => (true, "")
    };

Where can you use them

It's common to see the Property Pattern being used with switch expressions, but don't limit it to there.

Property Patterns can be used in the context of switch case guards, if's, boolean assignments, catch a condition, etc.

try
{
    //...
}
catch (NpgsqlException ex) when (ex is {Code: "42P01"})
{
    //...
}

Nested patterns

Property Patterns can be used to not only test properties but also nested ones. With C# 10 Extended property patterns, that becomes even simpler.

if (person is Student { Address.CountryCode: "PT" })

Precedence

With Property Patterns you will not be using "&&", "||" or "!", instead, you can use "and", "or", "not".

You can also use parentheses to specify the precedence.

person is Student ({ Address.CountryCode: "PT" } or { Address.CountryCode: "ES" }) and { Age: < 20}

Wrapping up

Next time you need to write a boolean expression, give what you have learned here a try. I know that at the moment, this is not that common in C# code bases, which increases the required cognitive load. It's a different way to write code if you are a long time C# Developer, but in the end, the code becomes more expressive in my opinion. What do you think?

I hope that this was useful! To get more tips like this, follow me on Twitter (@gsferreira) and let's keep in touch!

Where to place C#10 Global Usings

Guilherme Ferreira — Sat, 11 Dec 2021 00:00:00 +0000

The new C# 10 is packed with quality of life features. One that I'm definitively using is Global Usings.

In simple terms, Global Usings is a way to declare usings at the project level, so you don't need to declare them in every single file.

Why should I care?

That's a fair question, especially in the days where IDE's do most of the work for us.

Even then, declaring them at the project level will result in tidier source files. Let's be honest, how many times do you import System.Linq or your own Extensions namespace?

How can I do it?

Global Usings are simple to use. Simply add the global modifier to the using you want.

Adding the global modifier is the same as adding the same using directive to every source file in your project.

That leads to the question: Where should I declare my global usings?

I was facing that same question. 🤔

One thing was obvious to me. I should have a central place for it. Even Microsoft Docs say so:

You may add global using directives to any source file. Typically, you'll want to keep them in a single location. The order of global using directives doesn't matter, either in a single file, or between files.

But, where? In a Web or Console project, you may use "Program.cs" for it, but rapidly it may become cluttered. And if it is a Class Library?! There are no "Program.cs".

So I asked my Twitter friends what would they do.

(here)

If you take a look at the comments, you will see many good suggestions around adding a file to the root of the project. Name suggestions vary as you can see:

Globals.cs
GlobalUsings.cs
Imports.cs

That seems a good approach, but there was a comment by Martin Costello that made my mind.

My prefered way

Before going into Martin suggestion, it's important to say that you can not only declare global usings in a .cs file but also at the project file.

That can be done by adding a <Using> item to your project file.

<ItemGroup>
 <Using Include="MyAwesomeApp.Extensions" />
</ItemGroup>

In principle, I would prefer to declare my usings in C#. I don't love to edit my csproj files, but Martin remembered me that I can do it in a Directory.Build.props file (if you want to know more about this file, take a look at this post that I've written to see the potential).

(here)

So, what's the beauty of it?

The beauty of it is that if you place Directory.Build.props in the root folder that contains your source code, when MSBuild runs will add to every project the properties defined in the Directory.Build.props. So, if you want to do it Solution wise or even only for your Test folder, you can do it.

Wrapping up

I will be using Directory.Build.props for sure. At least until we see a new standard way to declare global usings emerging in the community.

I hope that this was useful! To get more tips like this, follow me on Twitter (@gsferreira) and let's keep in touch!

Uploading files with ASP.NET Minimal APIs

Guilherme Ferreira — Wed, 24 Nov 2021 00:00:00 +0000

With the .net 6 release, I was extremely excited to play with Minimal APIs.

One of the first things that I've done was to move an existing project to .net 6 and convert my Controllers into a Minimal API.

I've found the process easy, but I was surprised when the tests for an Upload endpoint failed.

My implementation after converting into Minimal API Endpoint was this. 👇

app.MapPost("/upload",
    async Task<IResult>(IFormFile request) =>
    {
        if (request.Length == 0)
            return Results.BadRequest();

        await using var stream = request.OpenReadStream();

        var reader = new StreamReader(stream);
        var text = await reader.ReadToEndAsync();

        return Results.Ok(text);
    });

And the test this. 👇

await using var application = new Application();
using var client = application.CreateClient();

using var formData = new MultipartFormDataContent();
await using var file = File.OpenRead("text.txt");
var streamContent = new StreamContent(file);
formData.Add(streamContent, "file", "text.txt");

var response = await client.PostAsync("/upload",
    formData);

response.StatusCode.Should().Be(HttpStatusCode.OK);
var data = await response.Content.ReadAsStringAsync();
data.Should().Be("\"Hello World!\"");

The expected 200 OK status code was now a 415 Unsupported Media Type 🤔

That was strange. My first thought was that I was missing to define the content type accepted by that endpoint.

.Accepts<IFormFile>("multipart/form-data");

I realized I was stupid by thinking that since the code above is just about adding OpenAPI Metadata. 😅

Then, finally, I got it. Minimal APIs will try to bind attributes with the assumption that content is JSON.

So, how do I handle it?

I had to receive the HttpRequest request as an argument.

Then, I was able to read the Form and look for files.

app.MapPost("/upload",
    async Task<IResult>(HttpRequest request) =>
    {
        if (!request.HasFormContentType)
            return Results.BadRequest();

        var form = await request.ReadFormAsync();
        var formFile = form.Files["file"];

        if (formFile is null || formFile.Length == 0)
            return Results.BadRequest();

        await using var stream = formFile.OpenReadStream();

        var reader = new StreamReader(stream);
        var text = await reader.ReadToEndAsync();

        return Results.Ok(text);
    });

In the end, it requires a lit bit of extra effort, but it's not a big deal. Maybe in a future version, we may have a simple way of accomplishing it.

I hope that this was useful! To get more tips like this, follow me on Twitter (@gsferreira) and let's keep in touch!

React components doing too much (and how to simplify them)

Guilherme Ferreira — Mon, 16 Nov 2020 10:00:00 +0000

Do you have the feeling that some of your components are doing too much?

Do you remember that time you added a new boolean prop to act as a flag to condition the render? That happens a lot, but those small changes sometimes can have huge impacts in the future.

Feature after feature, change after change, components tend to become more complex. If we are not watching for it, they will be out of control, and that will lead us to be afraid of change.

That's why we need to be careful with component contracts. That contract is expressed through props by the way.

One way to spot eventual problems is to look for boolean props (they will yell at you as you can read here). A usual case is to have boolean props used as a way to condition the render.

There are a few problems with that approach:

The component contract can become complex and the state of the component difficult to evaluate.
It can be a symptom that the component is doing too much.

Let's take a look.

Complex Contract

Imagine that you have to create a login Component where the user can log in using username.

import React from "react";

function Login() {
  return (
    <div className="Login">
      <form>
        <p>
          <label>Username:</label>
          <input type="text" />
        </p>
        <p>
          <label>Password:</label>
          <input type="password" />
        </p>
        <p>
          <input type="submit" value="Log In" />
        </p>
      </form>
    </div>
  );
}

export default Login;

One day, you have to review the login Component so the consumer can decide if the user will log in using username or email. A quick fix to achieve that is to create a component with a boolean prop in case the consumer prefers email:

import React from "react";
import PropTypes from "prop-types";

function Login({ usingEmail }) {
  return (
    <div className="Login">
      <form>
        <p>
          <label>{usingEmail ? "Email:" : "Username:"}</label>
          <input type={usingEmail ? "email" : "text"} />
        </p>
        <p>
          <label>Password:</label>
          <input type="password" />
        </p>
        <p>
          <input type="submit" value="Log In" />
        </p>
      </form>
    </div>
  );
}

Login.propTypes = {
  usingEmail: PropTypes.bool,
};

export default Login;

Now imagine that one day, users can also log in with phone number. Now you have a problem.

The boolean flag isn't extensible to support three variants, and following the same strategy, we would get contradicting boolean props. The consumer of the component would be capable of configuring the Component with a username and phone login, for example.

import React from "react";
import PropTypes from "prop-types";

function Login({ usingEmail, usingPhoneNumber }) {
  return (
    <div className="Login">
      <form>
        <p>
          <label>
            {usingEmail ? "Email:" : usingPhoneNumber ? "Phone" : "Username:"}
          </label>
          <input
            type={usingEmail ? "email" : usingPhoneNumber ? "tel" : "text"}
          />
        </p>
        <p>
          <label>Password:</label>
          <input type="password" />
        </p>
        <p>
          <input type="submit" value="Log In" />
        </p>
      </form>
    </div>
  );
}

Login.propTypes = {
  usingEmail: PropTypes.bool,
  usingPhoneNumber: PropTypes.bool,
};

export default Login;

Contracts with boolean flags are complex and deliver a bad UX to the consumer.

It complicates component signature, yelling that this component does more than one thing. It does one thing if the flag is "True" and another if the flag is "False". In the example, the worst is that the consumer doesn't know what to expect when both props are "True".

So, what to do?

A simple solution would be to prefer Enums over booleans. A boolean is extensible and describes a clear intention.

import React from "react";
import PropTypes from "prop-types";

const USER_IDENTIFIFICATION_TYPES = {
  USERNAME: "username",
  EMAIL: "email",
  PHONENUMBER: "phone",
};

function Login({ userIdentificationType }) {
  const shouldUseEmail =
    userIdentificationType === USER_IDENTIFIFICATION_TYPES.EMAIL;
  const shouldUsePhone =
    userIdentificationType === USER_IDENTIFIFICATION_TYPES.PHONENUMBER;

  return (
    <div className="Login">
      <form>
        <p>
          <label>
            {shouldUseEmail ? "Email:" : shouldUsePhone ? "Phone" : "Username:"}
          </label>
          <input
            type={shouldUseEmail ? "email" : shouldUsePhone ? "tel" : "text"}
          />
        </p>
        <p>
          <label>Password:</label>
          <input type="password" />
        </p>
        <p>
          <input type="submit" value="Log In" />
        </p>
      </form>
    </div>
  );
}

Login.propTypes = {
  userIdentificationType: PropTypes.oneOf(
    Object.values(USER_IDENTIFIFICATION_TYPES)
  ),
};

Login.defaultProps = {
  userIdentificationType: USER_IDENTIFIFICATION_TYPES.USERNAME,
};

export default Login;

As you can see, we fix the problem of the contract, but this component is doing too much.

God Components

Besides contract complexity, boolean props are a symptom that the component may be a God Component , doing too much.

So, what to do?

If you notice that you are in the presence of a God Component, you should split the component.

In this login component example, you could create three components, for instance, to encapsulate inner details, something like:

UsernameLogin
EmailLogin
PhoneNumberLogin

Base Login Component

import React from "react";
import PropTypes from "prop-types";

function Login({ children }) {
  return (
    <div className="Login">
      <form>
        <p>{children}</p>
        <p>
          <label>Password:</label>
          <input type="password" />
        </p>
        <p>
          <input type="submit" value="Log In" />
        </p>
      </form>
    </div>
  );
}

Login.propTypes = {
  children: PropTypes.node,
};

export default Login;

Username Login Component

import React from "react";

import Login from "./Login";

function UsernameLogin() {
  return (
    <Login>
      <label>Username:</label>
      <input type="text" />
    </Login>
  );
}

export default UsernameLogin;

Email Login Component

import React from "react";

import Login from "./Login";

function EmailLogin() {
  return (
    <Login>
      <label>EmailLogin:</label>
      <input type="email" />
    </Login>
  );
}

export default EmailLogin;

Phone Login Component

import React from "react";

import Login from "./Login";

function PhoneNumberLogin() {
  return (
    <Login>
      <label>Phone:</label>
      <input type="tel" />
    </Login>
  );
}

export default PhoneNumberLogin;

This way, your components will do one thing and do it well.

Hope that this was useful! To get more tips like this, follow me on Twitter (@gsferreira) and let's keep in touch!

Eleventy - The Simplest Static Site Generator

Guilherme Ferreira — Fri, 24 Jul 2020 21:47:00 +0000

Eleventy is the simplest Static Site Generator that I know. I know that this is a bold statement and you can prove me wrong. But Eleventy (11ty) was the simplest static site generator that I found when I needed to migrate my blog. Eleventy may not be the best or the powerful one but is beautifully simple.

The goal

I have been thinking about moving my blog to a different framework. I was using Sandra.Snow, that not have been updated recently.

My goal was to keep using a Static Blog, hosting on GitHub Pages. I want to write using markdown. It was also important to be able to keep the same URLs and migrate all the content to the new framework. I also would like the blog not need JavaScript to display the blog posts. Those are the requirements.

The obvious choices

In the top of my mind, I knew that Gatsby and NextJS were able to do the job. I was more inclined to try out Gatsby since there are many starters to create a blog. I don't have experience with Gatsby or NextJS, so, it was important to me to not need to much time to do the work. So, the learning curve was also an important factor.

My first attempt was with Gatsby. I installed the starter blog and I tried to migrate my content to Gatsby. I have to confess that after a few hours I was stuck. I couldn't accomplish my task without investing to much time to learn the framework. After a few problems, I was finding myself searching through the web to have a clue of what should I do.

Gatsby was taking so much time that I decided to take a bet on NextJS. I knew beforehand that I didn't have so many starters/templates as in the Gatsby ecosystem. Even so, I was expecting to have results faster.

I picked Telmo blog as a starting point and I tried to move my content. The results show up faster!

But, there was something that I didn't like and I didn't find a way to overcome. Even with the static HTML export build, I needed JavaScript enabled to display the content. Probably was because of my lack of knowledge, but after a few hours, I didn't have a clue of what should I do.

Eleventy

I was tired of fighting with Gatsby and NextJS. Something simpler was needed. I recall seeing a blog post from David Neal about moving his blog to a different technology. The technology is Eleventy. You can read his blog post here.

After reading a few things, I start feeling excited. Eleventy seems simple and quick to learn. The learning curve doesn't seem to steep. It feels natural to create pages with it. I see it as Templating Language on steroids.

So, I start working to move my blog into Eleventy. I started with the MF Blog Starter Template. After a few hours, I had most of the job done. Without tricks and without needing to search the web to find what I want. The Eleventy documentation was just enough.

I can't recommend it more. If you are planning to use a Static Site Generator, give Eleventy a try. Probably something simple is enough.

You can find here the source code for my blog. I hope it can be helpful.

Speaking at a Virtual Conference

Guilherme Ferreira — Wed, 08 Jul 2020 20:40:00 +0000

I had the honour of having one of my talks selected to NDC Oslo 2020. I was looking forward to speaking at Oslo Spektrum for the first time. This has been a wish for a long time.

Unfortunately, Coronavirus has destroyed those plans. NDC was converted into an Online Conference. With that, I was facing a new and different challenge: Virtual Conference Speaking.

If you had the chance of speaking in a virtual conference, you know that it's not the same experience. Even if you are an experienced Speaker, you will find yourself with strange feelings.

Fortunately, my talk went really well. So, this post serves to share what I have done to prepare myself. If you will be speaking in a virtual conference, this may be useful to you. My goal here is to describe what I've done and what I've learned. Hope it can be helpful to you.

Setup

Video

To me, image is an important part, and I didn't want to seem sloppy or unprofessional. Having a good camera is a must, but there are other things to consider.

Camera

I bought a Logitech C920. The image improved when comparing to the laptop webcam. Besides that fact, I'm able to use a tripod to hold the camera and align it with my eyes.

Aligning the camera with your eyes is useful. You will be speaking to a camera, so it's good to have it in the correct position. Level it with your eyes. It will feel more natural to you and to those that are watching.

Lighting

Lighting is a small investment that makes a huge difference in the result. You can always use natural light. In my case, I bought a simple light ring from AliExpress.

Background

If you don't have a green screen, you need to take care of your background. Having a lot of things happening in the background can be quite distracting. Remember that your goal is to get the attention of the audience. They are at home, on their computer, and they can easily be distracted when compared to a conference room.

I didn't want to give them another good reason for distraction by having shiny objects on the background.

So, I tried to create a minimalist background with a small décor to have a better look and feel than a white wall. I also used a led strip that I had at home to have a backlight.

Microphone

A decent microphone is a must. Using the laptop microphone is terrible. Dylan Beatie crafted an excellent blog post that can help. There you can also see the difference between different microphones.

In my case, the microphone was a concern, especially because I live in a noisy place with a ton of traffic. It's impossible not to listen to background noise in my house. So, I decided to invest in a USB Dynamic Microphone (SAMSON q2u).

So, I recommend you to find the quietest place you can and use a good microphone. At least, something other than your laptop microphone. If you don't have background noise, an inexpensive Condenser Microphone can improve your sound quality a lot.

I've found really good information about Microphones, Cameras and Lighting here.

Glare on Glasses

If you use glasses like me, Lighting and positioning can be quite difficult.

Facing direct light or bright screens was reflecting everything on my glasses.

Light and screen reflexes can be quite distracting and don't feel natural. To overcome it, I position my screens on a diagonal line and the light ring from top to bottom. Besides that, I reduced the brightness of my screens.

This video was really helpful.

Stand-up

By standing up, you will see that your voice will be clear and you will have a better posture. If not have a standing desk, improvise. I managed the same result by stacking up my kitchen table with my daughter´s playing table.

Preparing

Rehearse in the same environment and with the same setup that you will be using.
Record it and share it with your friends and colleagues. Ask for honest feedback. Use the feedback to improve.
Rehearse
Make sure that you have a Plan B

What if your computer fails?
Will you use a pointer? Do you have extra batteries?

Rehearse
Rehearse with the same software that you will be using in the day. Make yourself comfortable with it.

No. Rehearse written so many times isn't a mistake. Honestly, the most important thing that you can do is rehearse. Rehearse in the same conditions. Over and over again. By doing that you will feel more comfortable speaking to a camera.

The day

The day has been really pleasant to me. After multiple hours of rehearsing, I have found that my muscle memory kicked in. I didn't have the chance to feel stressed. I was feeling prepared. It was showtime and I was enjoying it. Nevertheless, there are a few things that helped me.

Dress-up

This will signal to your brain that it's time to do important stuff.

Barefoot

Barefoot or use socks. You will find yourself more relaxed. You will also make less background noise with your feet.

Shutdown your doorbell

Make the possible not to be interrupted. Delivery man ringing the doorbell, your partner walking by, your dog barking... Try to find a way to reduce the probability of something like that to happen. But, if it happens, embrace it. Play with it. Prepare a joke if you can.

Hydrate

Have a glass of water nearby. Do not forget.

Connect to the audience

You can't move around, so try to make your hands visible and use them to communicate. Use different tones of voice to keep people connected. Ask for feedback in the chat and try to keep an eye on the chat in case you are looking for a more interactive talk.

Always remember that those attending, are there because they want to learn from you. So enjoy!

That flag argument is yelling at you

Guilherme Ferreira — Wed, 27 May 2020 23:00:00 +0000

Sometimes the code yells at you trying to warn you that something is wrong.

Flag arguments are one of those cases. Adding a Boolean argument to condition the execution is an easy fix, but we are doing the wrong thing.

By adding a flag argument to a function, it's clear that we are ignoring the Single Responsibility Principle. The code is yelling at us, trying to explain that. No doubt.

Let's take a look. When a function has a flag argument, we will find something like this (or even worse) in the implementation:

Wouldn't be better to have something like:

When writing code, remember that the goal is to simplify our client's life.

Don't comment what your code is doing, comment the Why

Guilherme Ferreira — Thu, 21 May 2020 23:00:00 +0000

Code comments are a common topic of love/hate discussions. It's particularly interesting to see developers shifting opinion while experience grows.

Code Comments are a good idea because we are writing them down to help others. Even to help the future self. But we use a lot of comments that don't help. This explains the Comments bad reputation nowadays.

So, what can we do to improve our comments?

I use a simple rule: Explain the Why, not the What.

I see a lot of Comments that are explaining what the code is doing. That doesn't help.
The effort that we put to write a Comment must be invested refactoring the code (this is a good starting point).
When we need to describe the What is because the code isn't readable at all.

It's also pretty common to have obvious Comments. All we have seen that "// Get a Customer" comment in a "GetCustomer" method.

Those comments don't bring value. They raise the cognitive load required to read and maintain the code.

So, the idea is to let the code speak for himself. We only write comments, when we need to explain Why we have done something.

It's useful to understand why a piece of code was written in a certain way.
Those Why comments can help us out to understand that there's a particular corner case, or the reason for the followed approach, or that, because of a bug (Link the bug from the comment), we need to do that.
Those are a few examples, but you get the point.

Our code must be self-describing, but sometimes, we need to explain the Why.

And remember: don't Comment the code that you don't need anymore. Throw it away. In case you need it, it will be at the source control.

Manage your code as a successful restaurant

Guilherme Ferreira — Fri, 15 May 2020 05:00:00 +0000

Have you ever noticed that a successful restaurant has a shorter menu? Especially when compared to those who are struggling.

Why?! Simplicity!

When you keep things simple, you focus on fewer things. You give your best and you can focus your effort. You can try to improve and perfect all details.

But, when life doesn't work as we expect, we start throwing new dishes into the menu. Expecting to please everyone.

Spoiler alert: When you build something to everyone, you build it to nobody.

This isn't just the restaurants' reality. We see that in software too. When trying to convince new customers, throwing features into a product is usually the way to go. And it's hard to find a Product Owner who doesn't fight to have the team focused on new features.

What we should all be doing is to focus on what we have and what customers love. Those features have a margin to improve. Don't bring a new feature into the product just because a customer needs it. Bring it because is inevitable. Because it's obvious that your software will be so much better. Because you believe that you are in an especial condition and nobody can do it better than you. And don't forget to throw away stuff that doesn't "spark joy".

We can expand this concept to multiple software parts. High level, to a low level. Decompose the code in smaller objects or functions. Create focused "restaurants" specialized in one task. If you want Mexican food, you don't look for an Italian restaurant.

Treat your code as a garden, which deserves care and dedication. Don't write it and ignore it until a bug arises.

A chef who creates new dishes every single night will create a few stunning dishes for sure. But also, a vast number of massive failures.

Having a continuous improvement mindset is what makes us better than the rest.