Too many times, software engineers, myself included, write code before even thinking enough about it. This usually results in time wasted both in rewrites, refactors, or worse, removal.

I've been thinking a bit about when we should give feedback and the consensus is early, frequent and actionable. Yet, we also need to balance it with the cost of giving feedback because it takes effort and time.

Everyone should first ask this question, "Do I need to write code?" Sounds like a stupid question but when your job is writing code, it's easy to jump straight to it. If we don't ask ourselves that question, we likely have not fully understood the problem we are trying to solve. Writing code has to be the best way to solve the problem. Once the problem is understood, and the tradeoffs of writing and maintaining the code we write are worth it, then it's time to get some feedback.

Now, down to the nitty-gritty of it. There are many ways to get feedback on software engineering tasks. A non-exhaustive list includes meetings, code reviews, code pairing and RFCs. How should we decide when to use which form of feedback?

Going back to balancing cost vs benefit, it depends on how much we already know about the problem we need to solve, and what kind of feedback we are looking to get. Questions that we ask should help us determine how clear we are on the scope and how concrete this scope is. Some examples of questions that we should ask are as follows.

• What is the overall direction and strategy?
• Who are our stakeholders?
• How do we measure success or failure?
• Are we the best team or person for the task?
• Have we as a team done something similar before?
• How familiar is the task to the one executing?

Explore

If this problem hasn't been solved before and it's entirely new, meetings or RFCs are likely worth doing. Code shouldn't be written before the team is clear on the direction it's heading. Timelines need to be flexible and milestones, shorter because all of them could change once execution starts as we learn new information. You might not have all the details sorted out; what you're looking for is early feedback and agreement between stakeholders in the direction you are heading. If stakeholders are not technical, you'll need to simplify your explanations or split up the meetings and RFCs for different audiences.

Imagine having to change scope or direction once code is already written. From experience, it's costly and you would want to avoid it at all costs.

The length of this phase depends on the entire scope of the project. There might be various stakeholders from the C-suite down to the engineers in your team. Depending on your role and the size of the project, you might want to also split up meetings for discussions and meetings for decisions. This helps increase the quality of discussions and you can have more information on the table before proposing or making a decision.

Execute

Once everyone is clear on the direction of the project, it's down to the next most important bit – execution. I won't go into details about what good software engineering practices are because that would take up a lot more than one post but I'll assume that your team is aligned on those. If they aren't, no one can help you here.

If you or your team has not done this task before, it'd be worthwhile to start with code pairing. Feedback would be real-time and any decision would have to be taken by at least two people, which in software engineering, is usually already a good proportion of your team. If at least one person in the team has done a similar task before, it'll be worth having this person pair with someone that hasn't. A good team shares information to make better decisions and pairing helps in transferring this informal knowledge that might be difficult to write down. Every line of code written influences other lines of code so inconsistency is obvious and confusing.

The cost of code pairing is undeniably time, and probably more exhausting as it requires constant communication between two people. That said, most of the time, it's worth it as code quality is higher and the team communicates more effectively. When the pull request is finally created, it's just a formality.

If a task is very familiar to the team and the one writing the code is very familiar with it, it could be worth just jumping straight to creating the pull request. Feedback in the pull request is likely slower and less frequent but that's okay if there are only one or two minor comments.

Warning signs of creating the pull request too early is a long list of comments or one major comment that would cause a huge rewrite. If we observe that, to save everyone's time, it's better to take a step back and go back to the earlier stages of feedback.

TLDR

How much we explore depends on how many unknown unknowns we think there are. And once we are clearer on what we don't know and we are confident enough, we start writing code, learning more as we start executing. If we discover more unknowns along the way, we may need to take one step back and explore again. It's seldom a one-way street but more like a cycle of exploring and executing because there will always be something that we didn't realize we don't know.

As a software engineer, feedback comes in various forms. And we need to know the tradeoffs between each form before deciding which is best. Sometimes, ego comes in the way and we'll need to learn how to navigate others and our own ego to gather feedback and respond to it well. No one is perfect at it but like anything else, it gets easier with practice.

We are so used to graphical user interfaces that we forget computers started off without it. As a software engineer, there are many reasons why using the command line can help with development.

• Less context switching -> more focus
• Lightweight -> faster development
• Deeper understanding of tools and the computer
• Higher interoperability between computers

On an aside, the recent trend of containerization requires you to be familiar with the command line. With most containers being in linux and entering them would mean that there's no user interface so you have to depend on the good old fashion command line.

CLI Basics

I'll assume you're either using a Mac or a Linux because it might work differently in Windows. And most development machines are based of UNIX anyway.

With that, I'll be explaining some common command line commands that are present in most computers which I commonly use. They won't be exhaustive but I encourage you to read more of them in the Linux Pocket Guide.

cd

It allows you to go to a relative or absolute path.

cd child_directory  # relative path to child_directory 
cd /usr/foo/directory  # absolute path
cd ../sibling_directory  # go to parent directory then into sibling directory
cd  # without arguments returns you to the home directory

export

Creates environment variables. Note that you'll need to define these environment variables in a .zshrc, .bashrc or any file that loads when the shell is created if you want this environment variable to always be present. Otherwise, this environment variable would not persist beyond it's current shell.

export FOO=bar
echo ${FOO}  # would show `bar`

printenv

Helpful for debugging to figure out what are the current environment variables.

history

Prints the commands you have used previously. Helpful when used with grep.

alias

Does what it says.

alias gp='git push'
gp  # would be equivalent to typing `git push`

ls

Short for "list". Lists attributes of files and directories.

ls  # lists files in current directory
ls directory  # list files in that directory
ls -a  # lists all files, including hidden ones

mv

Short for "move". Move / Rename file(s) or directories.

mv foo.txt bar.txt  # renames foo.txt too bar.txt
mv blah.txt foo.txt destination_directory  # moves blah.txt and foo.txt to destination_directory

cp

Short for "copy".

cp original.txt copy.txt  # creates copy.txt which is a copy of original.txt
cp original.txt directory  # creates a copy of original.txt into `directory`

rm

Short for "remove".

rm foo.txt  # removes foo.txt
rm -r directory  # removes anything in this directory

pwd

Prints the absolute path of your current working directory.

mkdir

Short for "make directory".

mkdir foo  # creates foo directory
mkdir -p foo/bar/bar  # creates any parent directories if necessary

echo

Prints arguments passed into it.

echo foo  # prints `foo`

cat

Concatenates and print files. Basically just means printing the whole file.

less

Something like cat but good for larger text and if you want to browse by pages.

grep

Given some files, print lines which match a regular expression pattern. Pretty powerful stuff if you're well versed in regular expressions.

Given this file a_text_file.txt.

80 days around the world, we’ll find a pot of gold just sitting where the rainbow’s ending.
Time — we’ll fight against the time, and we’ll fly on the white wings of the wind. 
80 days around the world, no we won’t say a word before the ship is really back.
Round, round, all around the world. Round, all around the world. Round, all around the world.
Round, all around the world. 

grep time  # Time — we’ll fight against the time, and we’ll fly on the white wings of the wind.

touch

Usually used to create empty files since it creates the file if it doesn't exist. It also updates the modification timestamp and access timestamp of the file.

| (pipe)

Passes the output of the previous command to the next. This is the key to mastering the command line. Commands on it's own don't seem that powerful but combine them with each other and the possibilities are endless. And that's what the unassuming | (pipe) does.

cat file.txt | grep text  # finds `text` in every line in file.txt
history | grep git  # prints git commands you have used previously

xargs

Another powerful command that reads each line of text from the input and turns passes each of them to the next command and executes them. It'll be clearer when you try out the examples.

ls | xargs ls  # runs ls on all child directories and prints the result
grep foo --files-with-matches | xargs rm  # removes all files with `foo`

pbcopy (MacOS)

MacOS clipboard. Helpful when you want to pipe something to the clipboard.

cat file.txt | pbcopy  # copies file.txt contents to clipboard
grep foo | pbcopy  # copies any line with `foo` to your clipboard

Exploring tools

Now you know the basics, but you'll need to figure out how to use these commands on your own. Most commands have a help option.

ls --help
grep --help

If not, they would likely have a man or short for manual.

man ls
man cat
man echo
man grep

You might find the manual too verbose but I found this helpful tool called tldr  (https://github.com/tldr-pages/tldr) which summarizes the manual to useful cheatsheets for me.

Other useful commands

These require a separate installation that are not found by default and to me, are better versions of default commands, but require an understanding of them.

• z - a faster cd based on your history
• tldr - a quicker manual
• rg - a faster grep written in rust
• peco - a more interactive filtering tool
• entr - runs a command when input changes. I mainly use this for TDD to run tests when any file changes.
• tree - list contents of a directory in a tree-like format. Comes default with Linux, but you'll have to install it on MacOS.

These commands are just scratching the surface of what you can do, so the best way to try them out is to use them in your daily workflow.

I've also created a small practice file at https://gist.github.com/aaronmak/dcc479d30ec9e844d6756933f0f6886e if you'd like to get more familiar with your command line.

References

• Linux Pocket Guide - similar commands to MacOS but there are slight differences.

Thinking it was similar to building one had normal switches, I tried to build my first keyboard with hot swappable sockets. I was so wrong. Not only could I not find build logs of anyone who has built one, but soldering wires to the Kalih hot swappable sockets was so much harder. So please read on if you're as clueless as I was.

There are many build logs out there so I'll distill what I thought was helpful and share some mistakes I've made to prevent you from repeat them before continuing with the build log.

Helpful but not obvious

Soldering the copper tape first

Start with soldering the copper tape and not the wires, but leaving the top most switch unsoldered. The topmost switch should be soldered together with the wire.

I made a mistake of soldering the diodes first because most guides suggested it. To my horror, I found out later that the copper wire cannot be wrapped around the hot swappable sockets. So I had to sneak the copper tape under the existing wires, which probably added at least an hour or two to my build time.

Solder the diode as close to the socket as possible

None of the guides I read told me to do this even though some images I've seen hinted that. Or maybe everyone already knew that except me, a soldering noob.

Soldering the diode close to the socket (or switch) ensures that the diode doesn't move around too much. There's also less of a chance that the row wire would touch another.

Understand what you're building

There're many guides out there and some have subtle differences of how they wire the thumb cluster or the materials they use. Since it's my first time soldering a keyboard, I just followed a mishmash of the popular guides. I'm glad it worked out but I just didn't know what the options were and the tradeoffs I was making.

Took me a while to understand how the wiring allows the controller to know which key was pressed. So even though I followed the popular wiring guide at https://github.com/abstracthat/dactyl-manuform, I might not need to in the future. The QMK guide to split keyboard also suggested an alternative wiring to connect the 2 controllers which I didn't know existed until I flashed the controller.

Wiring Diagram

Not drawn to scale but hopefully it's clear. It's an svg file so you'll be able to zoom in as needed. I found that most diagrams don't have the reset switch and they only show one side at a time.

To understand this diagram, it is drawn from the perspective of the underside of the keyboard. The brown and black rectangles represent the diodes and the direction they need to be in for the current to flow the right way. I used elite-c's because I've read that pro micros are fragile but they work as well.

Building the keyboard

Materials and Tools

• 3D printed case with hot swappable kalih switches, base, wrist rests and elite-c holder printed by reddit user crystalhand
• 2 Elite C controllers
• 2 3.5mm TRRS sockets
• Reset button switch
• 64 Diodes (a few spare would be handy just in case)
• Solder core
• Solid core copper wires (from ethernet cables)
• 5mm width copper tape
• Soldering Iron
• Soldering Iron Tip Cleaner (An old wet cloth or sponge will do as well)
• Pliers
• Tweezers
• Digital Multimeter (optional, but useful for debugging and troubleshooting if something goes wrong)
• Screws, nuts and screwdrivers (optional, only needed if you want to cover the bottom or to attach the printed wrist rests)

Soldering the connections

I started with the diodes because I wasn't expecting to use copper tape later. So don't repeat my mistake and start with the copper tape instead. I was building the 5x6 version of the dactyl manuform so it wasn't too difficult finding wiring diagrams for it. As said in other build logs, winding the diode wire around the node would help. However, it'll be trickier to wind it around the hot swappable socket.

When you get to the corners, you'll likely have to use the tweezers to finish the job.

As you can see, some diodes are pretty far away from the sockets, which I'll live to regret later on.

Since I've started on the diodes, I continued by soldering the row wires. After removing the individual wires from the ethernet cable, I got to work. The wire stripper I got was too big so I had to return it, leaving the only other option which was to use the soldering iron to melt the insulation of the wires. That didn't leave me with the cleanest cuts but it worked.

Now for the columns! I assumed I could wind the wire around the socket like all the guides for the switches mentioned but I was clearly mistaken. The copper wires were a little thicker than the diode wires, which resulted in me being unable to wind them around the sockets. I saw some guides that used copper tape so I ordered them online.

After waiting for a couple of days for the copper tape to arrive from a local hardware store, I realised that it'll be difficult to get the tape under the wires. After much patience and perseverance, it was complete.

I found the thumb cluster to be insanely difficult with the copper tape so a tip is to plan where you're going place the tape.

Soldering the wire to the copper tape was also tricky because don't forget, I couldn't wind it around the socket. What I found helpful was to tape one side of the wire such that pressure was applied to the end of the wire in contact with the tape. I know it sounds vague so hopefully this next photo would help.

The exposed end of the wire was bent to be in contact with the socket and copper tape at the same time. With the masking tape helping it stay in place, soldering was more manageable.

Soldering the components

Once the rows and columns are complete, it was time to solder the components. Before soldering to the elite-c, you'll need to wind the exposed end of the wire around the side. It's not that clear but the wire needs to enter from the top and curl at the bottom because the soldering will be done below the controller. Ensure that this is done for all wires so it's consistent.

One mistake I made here was to not give enough slack for the wires so I had to solder 2 wires together because I realised one was too short. If you have the holder for the elite c, ensure that you have enough slack so that elite c can peek out through the cavity for the holder to fit.

Quite a few guides would suggest a specific GND position for the TRRS wire but any one of them would do as long as it's labeled GND. Since I was going to solder the reset switch to GND and RST, I used the GND adjacent to RST for the reset switch.

And before I knew it, I was finally done! Now came the easiest part, adding the switches and keycaps.

Flashing the controller

The open source program QMK is what you're looking for to configure it. For the first flash, I just got the defaults working so I could test out if any keys weren't working. Following the instructions, I used homebrew to install it on my mac. It was surprisingly easy to install.

brew tap qmk/qmk
brew install qmk

QMK is well documented and I'd advise you to read the documentation before continuing. After reading the documentation, I flashed the left side first and connect the right side for the default settings. And it seemed everything was going well.

It turned out I celebrated too early. After testing the keyboard at qmk, I found 4 keys that weren't working. Immediately, I rushed to get the multimeter to diagnose the issue. Finding out that the circuits were working fine which meant no more soldering, I heaved a sigh of relief. It was the switches' pins that were bent. After straightening them out, it was perfect.

After spending some time tinkering with the online configurator, I arrived with one which mimicked the layout of my ergodox. Don't worry if you don't know how to use a text editor or read C. The online QMK configurator and toolbox doesn't require you to use any text editor.

And after pressing the reset button followed by one final flash, that's it!

A few days in and I'm pretty sure I'll be using this keyboard for a long time to come.