DEV Community: Shane Kennedy

First 10 things to do at your new job as a junior dev

Shane Kennedy — Thu, 28 Apr 2022 11:42:02 +0000

This is a repost from my personal website, head over there to see more tutorials, tips and tricks I wish I had when starting out.

When starting a new job (from junior to senior) here are the first 10 things I like to do related to the code/project you're going to be working on.

There are a bunch of things you can do outside of the context of code, like starting to build your network at the company, setting yourself up for productive 1:1s with your manager and getting to know your team better that I won't cover in this post, but are all equally important, so don't forget these!

I'm also going to skip the "get your dev machine setup" suggestion (at least the most basic configuration of it). I assume this is a given if you're a developer: download your editor/IDE of choice, a terminal app if you want one, and any CLI tools that make you more productive in your normal workflows. If you need any suggestions, checkout Upgrade your command line.

I'm also going to assume you have an "onboarding buddy", someone who's responsible for making sure you're getting up to speed and someone you can ask a shameful amout of questions to (there's no shame in this, actually, but 3 jobs later and I still feel like I'm being annoying when I ask too many questions, even if I tell people that I onboard not to feel this way towards me). If you don't have an onboarding buddy assigned to you when you start, talk to your manager and get one; I promise you nothing will make your first 6 weeks at a company better than a good onboarding buddy.

In any of the following points you find yourself asking "how do I find this out?", ask your onboarding buddy. This is what they are there for.

1. Get a list of repositories you're going to need

Typically when you join a team you're responsible for a certain service, or area of the code/platform/product, so find out where your code lives and any dependecies it has to other repositories in your organization, and clone them to your local machine. When you finally start working in the code you're going to want to jump around alot trying to figure out how this code all works, and having everything in place will save you a bunch of time.

Each of these projects probably also have a very basic README.md to get each of them running, be sure to go through these as well.

2. Run the product/platform/service locally

This may sound obvious, but you would be surprised how many times I hear that people don't run their service locally, and that they rely on tests to verify their changes. While this might work in some cases, there's nothing that gives your more confidence that your changes work than to use the product/platform/service the way your users will. Maybe you won't always need to run your service locally, but someday you will and you don't want to be 6 months in to a job not knowing how to do this, because now you can't ask your onboarding buddy (of course you can, just not as shamelessly as you could 6 months ago).

3. Run the test suite

When you first jump into the code it's going to seem like a lot (because it normally is), and you're not going to be able to grasp it all at once. One thing that helps me onboard quickly is to find a module/package/class/function that I'm interested in, and find its test suite. Tests should be dumb and easy to understand: what's being tested, what the test conditions are and what the expectations of the test are. Tests are great for learning the codebase

Additionally, when you finally start coding, you're still not going to have in-depth knowledge of the codebase, product or platform, so tests are really all you have to make sure you're not breaking anything, so make sure you can run your tests locally!

4. Ask your team what tools they like to use

This is an easy but often overlooked tip: this will show you who likes similar tools to you and show you some new ones. Ask for any command line aliases or functions, too!

5. Find the "Getting started" guide for your team

This might exist as the project's README.md file, in a Confluence page, or any number of places really. If there isn't one already, consider taking notes on your onboarding experience: where to start, what wasn't completely clear, and what made no sense at all. Once you've onboarded, summarize this in a document and start your team's "Getting started" guide.

6. Check out your project's CI/CD

When it's finally time to open your first PR it will hopefully have to go through a bunch of automatic checks: tests, linting, etc. Figure out what these steps are and make sure you can setup some local tooling to avoid having to re-push little fixes like styling and commit message format.

7. Ask if there are any git conventions within the team or organization

Some of these conventions might be enforce in CI checks while others might just be agreed upon within the team as "best practices". Either way, find out what they are and learn to incorporate them into your workflow.

8. Note down some quick wins that you can get for yourself

One of the best parts of being new is that you're a pair of fresh eyes: you see problems that others don't want to, don't care to, or just don't see at all. Take note of where you can immdeiately start to add value, no matter how small. This not only adds value to the team, but demonstrates good initiative and some excitement from your side, both excellent qualities for your manager and peers to see.

9. Understand the deploy process

You just merged your first change into master/main.... what now???? Figure out if you have any staging environments, how often changes are pushed to production, and how/when you can verify them.

10. Observe your system

Find out what your team uses for your product/platform/services observability. Understand the load this system is under, how it's performing and what sort of indicators you can look for when your system starts to break.

This has ties to #8 and #9, in my experience the observability is always one of the least maintained parts of the product because its development is often reactive rather than proactive (aka it only gets updated after something goes wrong, and is ripe with quick wins). It's also where you're going to want to keep an eye on after you merge PRs (certainly after your first) to know if your change is performing under load in production.

Have any other tips? Leave them in the comments below! All feedback welcome :)

Upgrade your command line

Shane Kennedy — Wed, 16 Feb 2022 16:28:59 +0000

This is a repost from my personal website, head over there to see more tutorials, tips and tricks I wish I had when starting out.

Context switching in your workflow (the enemy)

Imagine you're writing a function that depends on a module in another one of your company's repositories; you probably don't have jump-to-definition capabilities here in your editor, which means you need to go find this module manually on your machine (if this sounds awful, it is. Consider this before going all in on multi-repo microservices). If every time you need to do this you need to re-remember/go look up commands, or just need to type a lot of tedious ones, it can take you right out of the context that you're currently focused on: writing code. Being slow at this isn't just annoying for you, it can be mentally draining.

The argument against speed - and why it makes no sense

People love to talk about how "speed doesn't matter" because "my editor/workflow isn't and shouldn't be the bottleneck when coding", and they're right. But no one is arguing that speed matters more than thinking about and designing your solution? Speed won't make your code better, but it does help with reducing lengthy context switching, and the general satisfaction of how you work, and this has been very important in my experience. There's nothing wrong with being new at something, but no one likes feeling like they're new.

Think about anything you've ever been good at: when you started you were probably slow, maybe it felt awkward, and maybe more importantly you might have been around other people who were doing the same thing as you but much, much faster. Not a great feeling. But as time went by and you got better, you got comfortable, you learned some tricks, and soon enough you were much faster than before. This is just a good feeling to have, regardless of what you're doing.

So let's upgrade that workflow

So now you've just started as a junior dev, working 8-10 hours a day and you're feeling slow, awkward and uncomfortable at all the things around coding; here are some tips, tricks and tools to help you get up to speed so you can focus on your code.

Your shell

Not everyone likes to work in the terminal, but if you do it's nice to have a shell that helps you out.

Zsh

zsh is an extension of bash with some nice improvements, and is now the default shell on new apple computers. Taking it one step further is oh-my-zsh, a framework for extending zsh with plugins and is what I personally use. This gives me a clean and helpful foundation for my terminal. Some of my favorite plugins are:

Fish

The friendly interactive shell or fish is a really interesting shell that takes a modern approach to shell configuration. Similar to oh-my-zsh there is oh-my-fish for extending this shell with plugins. The only reason I haven't switched from zsh to fish is crippling laziness.

Command line tools

z

If you work in lots of repositories you want z in your toolbelt. This cli tool keeps a history of directories you visit and makes jumping between folders much easier.

rg/ag

These are both improvements on grep. If you need to search for something in a project like where a certain class is defined, usages of a certain word (when your designer tells you we're no longer calling it by "x", it should now be "y"), these two are life savers. rg and ag can also act as backends for some editor plugins and some other tools in this post.

bat

bat is a pretty version of cat. Just nice to have some syntax highlighting when you're viewing a files contents in the terminal.

lsd

lsd more colors, this is just a nicer ls command. I have lsd aliased to ls because I have no reason to use ls with lsd installed and I can't be bothered to change my ls muscle memory.

fzf

fzf is a command line file fuzzy-finder. Super useful if you need to find the location of a file on the command line. You can also fuzzy-find-then-open-in-editor, which is :chefs-kiss:

pgcli/mycli

pgcli basically taught me sql, along with a very nice co-worker (aside, no book, cli, editor or blog post will help you improve faster than a good mentor). This provides IDE-like syntax completion for sql and is database-aware, i.e based on what database you're connected to it can provide completions for tables when joining. pgcli and mycli are the same programs for postgres and mysql, respectively.

Your editor

I'm not going to list any editors or tell you which one is my favourite. All I'm going to say is that this is where the majority of your work is going to be done, so no matter what you pick, really learn it. Know how to find files/symbols quickly, get used to the git client (if you like those), learn the refactoring tools where applicable, multiple cursors for quick renaming in a single file, learn how to use macros. I promise you, time invested in learning your editor pays dividends in time saved in the long run.

General advice

Automate when it makes sense

If you find yourself writing the same command(s) over, and over again, then it's probably worth your time to automate/streamline this.

Aliases

There is a general concept in shells that you can alias commands ex: alias ls="lsd" this means whenever I type ls in my terminal, lsd will actually be executed. But lots of CLIs let you provide aliases specific to that cli. Git is one of those programs and I have the following aliases in my .gitconfig:

[alias]
        co = checkout
        st = status
        lg = log --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit --date=relative
        lg2 = log --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cd) %C(bold blue)<%an>%Creset' --abbrev-commit --date=short
        search = log -p --all -S

This allows me to write git st instead of git status, which I previously mentioned I write all the time. The two log aliases are because the default log is not intuitive to read and the basic "git log --graph" is too verbose. Lastly, git search is more of a "I can never remember this so I will keep it here". Basically if you know you committed something in the past and it's since been deleted, for example a class that got refactored, you can do git search myclass and it will find commits where this class was added, modified or deleted.

Functions

If you find yourself writing the same multiple commands in succession all the time, you might want to write a bazh, zsh, fish function. I personally don't have any in use at the moment, but it's nice to know about these when you start noticing the pattern of repeating commands in succession.

"Dotfile" repositories

Dotfiles refer to files you keep in your home folder that command line tools typically look for for configuration such as ".gitconfig" ".zshrc" and are aptly-named "dotfiles".

In your career and life you're going to have multiple computers through different jobs, ones you buy yourself, and ec2 instances you rent; you don't want to rewrite your config every time. Consider version controlling your configuration files (or dotfiles) and pushing to your favourite git remote so you can access them whenever and wherever.

Interactive rebasing, git god-mode

Shane Kennedy — Tue, 08 Feb 2022 18:40:37 +0000

This is a repost from my personal website, head over there to see more tutorials, tips and tricks I wish I had when starting out.

Imagine you have this feature branch with 5 commits:

* 02a7e84ccee - (HEAD -> billing, origin/billing) Fail gracefully if unknown error (8 hours ago) <Commit author>
* 8647daf1a2f -  Add R0801 to pylint ignore list (8 hours ago) <Commit author>
* 1c5d459147a -  Don't use BaseException anywhere (8 hours ago) <Commit author>
* 62de8bb854d -  Send billing events (8 hours ago) <Commit author>
* d783109d594 -  Raise insuffient data exceptions (8 hours ago) <Commit author>
* d8d58d1f055 -  Update event service client with billing logic (8 hours ago) <Commit author>

You've put the work in to reflect incremental units of change, each with their own value, as well authored commits and you open a PR. Overall the PR looks good, but your reviewer found a few issues:

Typo here
Missing edge case there
Missing test somewhere else

What we could do is create a commit that fixes the typo, handles the edge case and adds a test called "Update with PR feedback", but I'm here to tell you that we can do better than that. A commit that fixes mistakes that were introduced in this PR does not make any sense. In the git history we would just prefer that these mistakes never existed at all. So let me propose a different way:

Let's add a new commit for each fix we make

Fix typo
Handle edge case
Add test

These are bad commit messages but you'll see why in a second. Further, let's say we know that the typo happened in "d8d58d1f055 - Update event service client with billing logic", the edge case was missed in "d783109d594 - Raise insuffient data exceptions", and that you missed a test in "62de8bb854d - Send billing events".

So now our commit history looks like this :

* da7f3059367 - (HEAD -> billing) Add test (1 second ago) <Commit author>
* e62d6fd4bab - Handle edge case (38 seconds ago) <Commit author>
* 01507911dfd - Fix typo (2 minutes ago) <Commit author>
* 02a7e84ccee - (origin/billing) Fail gracefully if unknown error (8 hours ago) <Commit author>
* 8647daf1a2f - Add R0801 to pylint ignore list (8 hours ago) <Commit author>
* 1c5d459147a - Don't use BaseException anywhere (8 hours ago) <Commit author>
* 62de8bb854d - Send billing events (8 hours ago) <Commit author>
* d783109d594 - Raise insuffient data exceptions (8 hours ago) <Commit author>
* d8d58d1f055 - Update event service client with billing logic (8 hours ago) <Commit author>

What we're going to do here is combine, or fixup, these small fixes with the commit where the problem was introduced; this means I'm going to combine "01507911dfd - Fix typo (2 minutes ago)" with "d8d58d1f055 - Update event service client with billing logic" and so on.

Rebase recap

If you haven't already read my intro to git rebase, that's a good place to start in order to understand rebasing in general. TL;DR rebasing is to re apply commits on top of some base. In my other article we talked about rebasing feature branches on top of the master/main branch, but here we just want to modify the commit history that's unique to our branch (the commit listed above), so in this case, we want our base to be whatever comes before our earliest commit. Let's learn by doing and rebase this branch -- interactively:

Command: git rebase <options> _base_ where base is what you want to re apply commits on to. In my previous post, we wanted to rebase on top of master/main so we would write git rebase origin/main. But here we just want to rebase on top of what came before our earliest commit: git rebase <commit-sha> but this can be a bit tideous to do, so I prefer to use git rebase HEAD~n where n is the number of commits back to the base commit.

--interactive or -i

I have 9 commits in this branch, which means the base that I want is 10 commits back:

git rebase -i HEAD~9

pick d8d58d1f055 Update event service client with billing logic
pick d783109d594 Raise insuffient data exceptions
pick 62de8bb854d Send billing events
pick 1c5d459147a Don't use BaseException anywhere
pick 8647daf1a2f Add R0801 to pylint ignore list
pick 02a7e84ccee Fail gracefully if unknown error
pick 01507911dfd Fix typo
pick e62d6fd4bab Handle edge case
pick da7f3059367 Add test

#
# Commands:
# p, pick <commit> = use commit
# r, reword <commit> = use commit, but edit the commit message
# e, edit <commit> = use commit, but stop for amending
# s, squash <commit> = use commit, but meld into previous commit
# f, fixup [-C | -c] <commit> = like "squash" but keep only the previous
#                    commit's log message, unless -C is used, in which case
#                    keep only this commit's message; -c is same as -C but
#                    opens the editor
# x, exec <command> = run command (the rest of the line) using shell
# b, break = stop here (continue rebase later with 'git rebase --continue')
# d, drop <commit> = remove commit
# l, label <label> = label current HEAD with a name
# t, reset <label> = reset HEAD to a label
# m, merge [-C <commit> | -c <commit>] <label> [# <oneline>]
# .       create a merge commit using the original merge commit's
# .       message (or the oneline, if no original merge commit was
# .       specified); use -c <commit> to reword the commit message
#
# These lines can be re-ordered; they are executed from top to bottom.
#
# If you remove a line here THAT COMMIT WILL BE LOST.
#
# However, if you remove everything, the rebase will be aborted.
#

This is what you should see in your git commit editor. Let me point out some interesting information:

Next to all of the commits we have the word "pick"
The command list that includes the various options we have and their explanations
This is an editable file: we can change whether we "pick" certain commits, we can move commits up or down etc.

Looking at the descriptions for each command:

Pick - "use commit" this means leave it as is
Reword - don't like the commit message you used?
Edit - forgot something on this commit?
Squash - "meld" into previous commit (this is what we want to do)
Fixup - same as squash, but use the first commit's message (this is also what we want, and what we'll use because I like the commit messages I made initially)
...

You get the point, I find these first four to be the most used in my workflow but the other options are worth knowing about.

Back to our rebase!

I want to take my small fixup commits, and "meld" them onto the commit where they were introduced:

pick cc449795730 Update event service client with billing logic
fixup bd8222bd083 Fix typo
pick a96ad17080a  Raise insuffient data exceptions
fixup 9c8776fbe9f Handle edge case
pick 745554d6aa5 Send billing events
fixup 3eef03eb869 Add test
pick a5487033dbb Don't use BaseException anywhere
pick aaebfa866a2 Add R0801 to pylint ignore list
pick ab307ed1550 Fail gracefully if unknown error

Your rebase file should now look like this after you moved the fixup commits one spot after where the thing they're fixing was introduced, and then changed "pick" to "fixup" because we don't want those little fixup commits in our git history.

Now save and close the file and run git log --graph

--graph is a preference, use normal git log if you want

* 9857802cbb1 - (HEAD -> billing) Fail gracefully if unknown error (5 seconds ago) <Commit author>
* 747321db1e0 -  Add R0801 to pylint ignore list (6 seconds ago) <Commit author>
* cbd6a8442b7 -  Don't use BaseException anywhere (6 seconds ago) <Commit author>
* 6f1f0da8a9d -  Send billing events (6 seconds ago) <Commit author>
* 158da739da5 -  Raise insuffient data exceptions (6 seconds ago) <Commit author>
* 4f702d469e3 -  Update event service client with billing logic (6 seconds ago) <Commit author>

And there you go! Those fixup commits are gone, but their changes are in the commits that they were squashed onto (use git show <sha> to see for yourself).

Some important things to notice: similar to rebasing on top of master like in my last post, you'll see that all of the commit hashes have changed, even for the commits that weren't changed. Go read that previous post for the explanation why.

The time stamps were modifed as well: before most of my commits were from 8 hours ago, and now it's saying 6 seconds ago. This is because they're new commits.

Your first taste of emacs

Shane Kennedy — Tue, 08 Feb 2022 18:22:03 +0000

This is a repost from my personal website, head over there to see more tutorials, tips and tricks I wish I had when starting out.

Foreword

There are a few reasons why you might be here reading this article

You heard emacs is an editor for "Hardcore Devs" on some thread about what editor is best
You know or work with an emacs user who's pretty good and think it's worth trying out
You pair programmed with an emacs user who was lightning quick and their answer to "how did you ..." when you inevitably asked was: "emacs"

If you're here because of 1. then let me be the first to say that this article probably isn't for you. A developers choice of editor and their skill have no correlation. I know great devs who use emacs, vim, vscode and IntelliJ/jetbrains. The ability to be a good software engineer has nothing to do with your editor.

In my opinion Emacs is for people who are obsessed with, or atleast firmly interested in, efficiency in their coding. Emacs is a good choice for these types of people because emacs is nearly unuseable out of the box and this forces it's users to customize it completely. This forceful way of making users create the experience they want is why, in my opinion, you see developers like the one mentioned above in 3.; you are forced to really learn your editor, so when you find some sort of inefficiency while programming, you know how to set a keybinding, write a custom function, create a new tool, of look for an existing tool. And this tutorial is for people who identify like this.

So with that out of the way, let's get started.

What is emacs?

If I had to simplify this as much as possible, I would describe emacs as a lisp interpreter with some added functionality for editing text. What do I mean by emacs being a lisp interpreter? I can open a file, write some (emacs-flavoured) lisp, and immediately evaluate it: (message "Hello world") -> M-x eval-buffer and a "Hello world" message is logged to the *messages* buffer (a temporary file that's created when emacs is started for logging purposes). Emacs being a lisp interpreter is a very simple, yet powerful concept that enables extreme customizability and is why Emacs is one of the oldest editors in the programming world that has stood the test of time and is still used by many devoted fans today.

What are my basic requirements for an editor?

When I start hacking on a project, whether I'm starting it from scratch or I'm jumping in to a large complex codebase, I have a few must haves that are non-negotiable if I'm going to be doing non-trivial work (i.e more that just updating a single file to submit a patch):

Searching/finding - I need to be able to quickly find files and/or keywords/usages in a project. (All self-respecting editors can do this, but emacs packages help do it on steroids).
Syntax highlighting and smart completion for languages that I work with. This is the most trivial box that pretty much any editor can tick for me.
Quickly build and test my project/source files (this is where most other editors fall short for me).

With all that in mind let's get our first taste of emacs.

Emacs terminology and basics for this tutorial (don't skip this!)

Emacs commands are executed with C-*, M-* or C-M-*, "C" is the control key, and "M" is the meta key which is not really a key on modern keyboards anymore, but maps to the "option" key on a Mac (later we'll switch this to the "Cmd or Command" key on Mac because I find that easier, but if you don't mind using the option key then skip that step!)
Frame: what you normally call a "window" for GUI applications, basically it's one running instance of an emacs client. Each frame holds atleast one window
Buffer: used to hold the contents of files that are being visited
Window: the area of screen that displays a buffer
Cutting and pasting: in emacs this is called killing and yanking, respectively (read more here), for legacy reasons that aren't important here. To cut or kill a highlighted area: C-w and pasting or yanking: C-y.
If/when you get stuck in some command and you don't know how to get out of it, spam C-g (This is probably the most important command in all of emacs).

TL;DR

If you don’t feel like going through this tutorial step by step and just want the code, you can find it at my emacs-light repo. Follow the README there to get started.

Let's start

Disclaimer, this is going to be a MacOS walkthrough because most devs work on macs afaik because their company requires it, but if you're on linux 95% of this should be applicable and the other 5% should be easy enough to figure out. If you're on windows you can use the Windows Subsystem for Linux.

As you may have heard/seen, most people configure their emacs/vim with "dotfiles" that are loaded when you start emacs/vim. We'll get there, but first I'm going to show you why the idea that Emacs being a lisp interpreter is so powerful.

I'm going to assume you have emacs installed already (if you don't, go do that), so open a terminal in your home directory and run emacs which should open up a blank, bland window for you with a bunch of intro information (if this has errors open emacs from your Applications folder).

I'm going to hold your hand through the first few steps because raw emacs has a.... not so modern first-time-user-experience -- to put it lightly.

Press C-x and then C-f. You should then see the "mini buffer" at the bottom that's indicating that you are in the home "~/" directory. This key-combination is mapped to find-file, an emacs function for finding files from your current directory (for us, this is the home directory "~"). Type .emacs and hit enter. This has just created a new buffer for a file named ".emacs" in your home directory.

The next thing I want you to do is press M-x and type emacs-lisp-mode and then press enter RET (enter). We've learned two things here:

M-x is where you find all emacs functions
The idea of modes - this is a big topic in and of itself, but for now it's important that each language needs a mode so that emacs can understand how to treat it (syntax highlighting, language specific refactoring, code execution etc.)

What we just did is make emacs think that this is an emacs-lisp (elisp) source file by enabling emacs-lisp-mode. You configure emacs by writing elisp, which it can then interpret and evaluate. What we're going to do is write elisp in this file ".emacs" and evaluate this file step by step so you can see how emacs changes at each step of the way.

Like I said before, we're about to configure emacs with elisp and so this is a configuration file; but we're not going to write every last bit of functionality from scratch! Like most text-editors/IDEs today, emacs has a package system, and this configuration file will consist primarily of declarations for which packages we want emacs to use.

Emacs packages are written in elisp and are hosted on various package repositories such as Milky Postmans E-Lisp Package Archive, or, MELPA.

Now let's get started!

By now you should be in a file called ".emacs" and have enabled emacs-lisp-mode. Lets start by configuring some package repository information:

(require 'package)

;; Nice macro for updating lists in place.
(defmacro append-to-list (target suffix)
  "Append SUFFIX to TARGET in place."
  `(setq ,target (append ,target ,suffix)))

;; Set up emacs package archives with 'package
(append-to-list package-archives
                '(("melpa" . "http://melpa.org/packages/") ;; Main package archive
                  ("melpa-stable" . "http://stable.melpa.org/packages/") ;; Some packages might only do stable releases?
                  ("org-elpa" . "https://orgmode.org/elpa/"))) ;; Org packages, I don't use org but seems like a harmless default

(package-initialize)

;; Ensure use-package is present. From here on out, all packages are loaded
;; with use-package, a macro for importing and installing packages. Also, refresh the package archive on load so we can pull the latest packages.
(unless (package-installed-p 'use-package)
  (package-refresh-contents)
  (package-install 'use-package))

(require 'use-package)
(setq
 use-package-always-ensure t ;; Makes sure to download new packages if they aren't already downloaded
 use-package-verbose t) ;; Package install logging. Packages break, it's nice to know why.

;; Slurp environment variables from the shell.
;; a.k.a. The Most Asked Question On r/emacs
(use-package exec-path-from-shell
  :config
  (exec-path-from-shell-initialize))

Ok all this code so that we now have access to use-package. From here on out, when we want to install and make a package available to emacs all we need to do is add (use-package package-name) which will pull the package source files from the repositories we enabled above: melpa, melpa-stable, and org-elpa, install them and load them into emacs.

Now lets evaluate this code: M-x eval-buffer

Nothing noticeable changes here because we just configured a package manager, but now lets install a theme from an emacs package, and enable it (because let's face it, the default in emacs is not very pretty).

(use-package doom-themes
  :init
  (load-theme 'doom-one))

Before when we configured the package manager there was a bunch of code and it was all new so it made sense to just go ahead and evaluate the whole buffer. But here we just added these few lines, why re-evaluate the whole thing? Put your cursor anywhere inside the (use-package...) parens, then hit M-x eval-defun (this function also has a keybinding C-M-x, remmeber this, we're constantly going to be evaluating elisp chunks like this).

You are probably going to get prompted with a yes/no for trusting this theme now and in the future (after all even themes in emacs are just elisp, so don't evaluate any elisp/themes you don't trust! But we trust the doom maintainer, so go ahead and type yes)

Tada! You just downloaded an emacs package of themes, and told emacs to load one of them and it works!

A few more UX importvements

;; Any Customize-based settings should live in custom.el, not here.
(setq custom-file "~/.emacs.d/custom.el") ;; Without this emacs will dump generated custom settings in this file. No bueno.
(load custom-file 'noerror)

;;; OS specific config
(defconst *is-a-mac* (eq system-type 'darwin))
(defconst *is-a-linux* (eq system-type 'gnu/linux))

;; Emacs feels like it's developed with linux in mind, here are some mac UX improvments
(when *is-a-mac*
  (setq mac-command-modifier 'meta)
  (setq mac-option-modifier 'none)
  (setq default-input-method "MacOSX"))

;; Some linux love, too
(when *is-a-linux*
  (setq x-super-keysym 'meta))

;; Fullscreen by default, as early as possible. This tiny window is not enough
(add-to-list 'default-frame-alist '(fullscreen . maximized))

One more eval trick: highlight the code you just pasted in and run M-x eval-region.

From here on out your Meta (M-*) key is now the command key (if you're on a Mac). I find this 100x better than the option key, but feel free to pick and choose from this block.

One final block of UX improvements that will be much appreciated, I promise.

;; Make M-x and other mini-buffers sortable, filterable
(use-package ivy
  :init
  (ivy-mode 1)
  (setq ivy-height 15
        ivy-use-virtual-buffers t
        ivy-use-selectable-prompt t))

(use-package counsel
  :after ivy
  :init
  (counsel-mode 1)
  :bind (:map ivy-minibuffer-map))

Highlight this region and do M-x eval-region again to let these changes take effect. Now hit M-x again and see that you now can see everything in emacs at your finger tips; from now on you'll be able to search and discover all of the emacs functions that you can interact with through M-x. Let's keep going.

Let's start with my first necessity in an editor: "Searching/finding - I need to be able to quickly find files and/or keywords/usages in a project."

For this we're going to use a mix of two packages: projectile and counsel-projectile

;; We need something to manage the various projects we work on
;; and for common functionality like project-wide searching, fuzzy file finding etc.
(use-package projectile
  :init
  (projectile-mode t) ;; Enable this immediately
  :config
  (setq projectile-enable-caching t ;; Much better performance on large projects
        projectile-completion-system 'ivy)) ;; Ideally the minibuffer should aways look similar

;; Counsel and projectile should work together.
(use-package counsel-projectile
  :init
  (counsel-projectile-mode))

Highlight the region, M-x eval-region and now if you check M-x projectile- you should have a bunch of possible commands for registering projects, switching to them, finding files and searching files.

Let's try an example M-! git clone https://github.com/codemirror/CodeMirror.git ~/code-mirror(Notice when you type M-! the mini buffer pops up with a shell command prompt? This is great for running quick commands). CodeMirror isn't tiny, this might take a few seconds...

Now lets register CodeMirror as a project M-x projectile-add-known-project and then find the path where you just cloned the repo to (~/code-mirror if you followed the above directly).

Now lets open the project M-x projectile-switch-project (Maybe open a new buffer in emacs first so you don't lose your config file, we're going to work in this project for a little bit C-x 3 to open a window to the right). code-mirror should be the only project registered, so choose that and then you should be shown a list of files in the project that you can open; lets choose src/modes.js.

Projectile rapid fire:

How can I register another project? M-x projectile-add-known-project
How can I switch to another project? M-x projectile-switch-project
How can I search for other files in this project? M-x projectile-find-file
How can I do find-and-replace in this project? M-x projectile-replace
How can I search for strings/words in this project? M-x projectile-grep or M-x projectile-ag or M-x projectile-rg (I recommend rg but it's seperate from emacs so you'll need to install it. If you don't want to bother with that, use projectile-grep, but grep is noticeably slow on larger projects).

This will open a buffer with a list of occurences which is nice, but counsel-grep/ag/rg will show you results in the minibuffer so that you can quickly see your search results without opening another window. It's excellent, I don't know of any other editor that has this.

Bonus: Another gem in emacs comes from the ivy package we installed earlier for searching within a file M-x swiper

On to my second necessity in an editor "Syntax highlighting and smart completion for languages that I work with."

Emacs comes with a bunch of built-in language modes for popular languages such as python, js etc. but let's configure completion capabilities.

;; Company is the best Emacs completion system.
(use-package company
  :bind (("C-." . company-complete))
  :custom
  (company-idle-delay 0) ;; I always want completion, give it to me asap
  (company-dabbrev-downcase nil "Don't downcase returned candidates.")
  (company-show-numbers t "Numbers are helpful.")
  (company-tooltip-limit 10 "The more the merrier.")
  :config
  (global-company-mode) ;; We want completion everywhere

  ;; use numbers 0-9 to select company completion candidates
  (let ((map company-active-map))
    (mapc (lambda (x) (define-key map (format "%d" x)
                        `(lambda () (interactive) (company-complete-number ,x))))
          (number-sequence 0 9))))

;; Flycheck is the newer version of flymake and is needed to make lsp-mode not freak out.
(use-package flycheck
  :config
  (add-hook 'prog-mode-hook 'flycheck-mode) ;; always lint my code
  (add-hook 'after-init-hook #'global-flycheck-mode))

;; Package for interacting with language servers
(use-package lsp-mode
  :commands lsp
  :config
  (setq lsp-prefer-flymake nil ;; Flymake is outdated
        lsp-headerline-breadcrumb-mode nil)) ;; I don't like the symbols on the header a-la-vscode, remove this if you like them.

Highlight, M-x eval-region, and try typing "(use-" in your current file and see the completion dropdown (if you're not seeing it, try C-. you won't have to do this every time, but sometimes I notice it doesn't initialize properly). This completion is the company package at work.

Now for an example, lets make use of the CodeMirror repo that we cloned earlier. Open up src/modes.js in CodeMirror and Run M-x lsp. This will prompt you to choose a language server, choose ts-ls and it will begin downloading it for you. Once it's done, it will ask you where the project root is (~/code-mirror).

To make sure the language server is working, move your cursor to line 1 in modes.js on to copyObj and then M-x lsp-go-to-implementation and you should jump to a file called "misc.js" where the function is defined. Great, so lsp is analyzing the codebase which means we have some smart completion.

And now for my final essential in an editor: Quickly build and test my project/source files

As I mentioned above this is where most editors tend to fall short for me; the reason being that it can be hard to just test one function at a time, it runs in some special test window which makes it different to go debug, or it's just not fast enough to go from writing/modifying a test to executing it.

Since we're working on a javascript project, we're going to install a package called npm.el which will provide some handy functions for quickly running npm commands.

(use-package npm)

Put the cursor inside the parens and C-M-x to evaluate that function.

Now back to the code mirror (reopen misc.js, or any file in the project if you don't still have that open) and run M-x npm and you'll see a menu pop-up on the bottom with a few possible npm options. We're going to start with npm install, choose "i" and when it asks for a package name leave it blank to simply run npm install to install everything in package.json. When that finished lets try "run", M-x npm and press "r" and you should get a list of options to choose from, choose one and hit Enter. You should see a new buffer open that's running the command you chose. This is called a compilation buffer and it's very useful when you are repeatedly running a certain command, like when using TDD or refactoring a module and frequently need to re-run tests. To re-run the command that you chose earlier, you don't need to go through the entire M-x npm flow again, you just need to switch to that buffer and hit "g"; this is a special command in "compilation-mode" which means "recompile".

And there you have it, lightning speed building and testing in javascript projects. But this type of flow isn't limited to javascript; there are packages for all sorts of languages, build tools and other technologies you're working on; just checkout MELPA. And as a last resort, you can always M-x compile and write out the command you want manually to get a compilation buffer that you can M-x recompile as you need.

To save this file so that emacs starts with this configuration the next time you open it hit C-x s.

This is the bare minimum emacs configuration for what my basic needs in an editor are, but the emacs world is vast and exciting to explore. Follow some emacs-ers on github, checkout youtube, and read blog posts to see all kinds of interesting things you can do with emacs.

Appendix

Commands and keybindings

These are some of my most used commands, some of them are built in to emacs and others come from the packages installed in this tutorial. If they have a default keybinding then I've listed it below but if not I've left it as N/A

Command	Keybinding	Description
swiper	N/A	Search within the current buffer for a string/regex and results are dislplayed in the minibuffer
counsel-rg	N/A	Search the entire current project for a string/regex using ripgrep and results are displayed in the minibuffer
projectfile-find-file	N/A	Search your current project for a filename
ivy-switch-buffer	`C-x b`	Switch to another previously opened buffer
delete-window	`C-x 0`	Delete the current window
delete-other-windows	`C-x 1`	When you have a bunch of windows this bufferes open at once and need to just delete them all except the one you're working on
split-window-right	`C-x 3`	Open a new window to the right
save-buffer	`C-x s`	Save the contents of the buffer you're working on
comment-line	`C-x C-;`	Comment out the current line
kill-region	`C-w`	Copy highlighted text
yank	`C-y`	Paste from clipboard

Package recommendations

A great package for learning emacs is which-key. This package makes a minibuffer popup with a key map based on the last key you just pressed (i.e if there are any). Add (use-package which-key :config (which-key-mode t)) to your config and try pressing C-x to see what options you have from there.

Magit is the best git client you can get. All other git clients should aspire to be how great Magit is.

diff-hl Git diff markers in modified buffers. Nice to see which lines you've added, changed and deleted, visually.

smart-parens bracket/parens matching is nice

Doom emacs and Spacemacs

Doom emacs and Spacemacs are "emacs distributions": when installed you get an entirely pre-configured emacs with all of the nice bells and whistles already there for you. I personally started with spacemacs and then moved to my own emacs config later. One massive caveat for spacemacs is that it is highly intergrated with the "evil" package, which means it uses vim keybindings. While you can disable "evil-mode", the configuration will be greatly hindered without it.