Alphabetize your Way to More Readable Code

Todd Eidson — Sun, 03 Mar 2019 20:31:55 +0000

Originally posted on my personal blog.

Alphabetize your Way to More Readable Code

Super short and simple post this time, because it's explaining a simple concept. The concept is so simple, that I'm slightly embarrassed, almost shocked, that it took me almost 7 years of professional programming, and 3 and a half years of college to see and use this pattern.

The tip? Any time you are writing code and the order of the lines is irrelevant, such as declaring class variables, creating a JSON object, populating an associative array, adding dependencies, configuring your configuration, ad infinitum, use alphabetical order.

Instead of:

{
  name: "Marshall Mathers",
  palms: "sweaty",
  knees: "weak",
  arms: "heavy",
  nervous: true,
  sweater: "mom's spaghetti"
}

Use this:

{
  arms: "heavy",
  knees: "weak",
  name: "Marshall Mathers",
  nervous: true,
  palms: "sweaty",
  sweater: "mom's spaghetti"
}

Sure, it does not rhyme as well, but if you need to change nervous to false, it is much easier to find in the list. It does take a little extra brain power to add an item to the list, instead of just appending to the list, you may have to sing a phrase of the alphabet (unless you have a tool that sorts for you, see below). However, since code is read at an average of 10 times after it is written, you'll see the pay off when looking through a long JSON object or associative array to alter or fix something.

I used to try and use some sort of hierarchical order with grouping in most places that I use this now, but there is no real hierarchy in most places that this can be implemented. Take for an example a 'person' object or class. Sure, 'name' is pretty important and would always go first (if not a uid), but how do you order the rest of the fields? Is a phone number more or less important than an address? As far as packages and dependencies go, one package might be used a lot more than another package, but I'd argue that one is no more important than the other. If it wasn't important, it wouldn't be a dependency. In fact, it was when I started a new Symfony project a few months ago and noticed that they had added "config": {"sort-packages": true} to composer.json and the profound effect that it had had on the readability of the "require" section as to what packages I was using in a project that I it had dawned on me that I should be using alphabetical order in as many places as I could to improve readability.

It wouldn't really feel like one of my blog posts if I didn't somehow mention my favorite IDE, PhpStorm, so here it is: I've recently discovered a plugin, called Lines Sorter by Sylvain Francois, that will do your sorting for you. After you have the plugin installed, highlight the lines you wish to have sorted and then in the menu go to Edit>Sort Lines or use the keyboard shortcut alt + shift + L (I had to unmap this shortcut from the default 'Load Context' option, first). This plugin will work in any of the JetBrains IDEs.

Is this something you've been doing for years? Do you have any tips that are so simple you can't believe how long it took you to incorporate them? Do you know of a VS Code plugin to accomplish this? Any arguments against using this tip? Please let me know in the comments.

Global Hooks with Git

Todd Eidson — Wed, 20 Feb 2019 18:35:46 +0000

Originally posted on my personal blog.

Global Hooks with Git

Introduction

Recently I began to wonder if there was a way to have a collection of git hooks that could run on all of my git projects to save me the trouble of creating/editing hooks in each of my projects. Yes, it is possible to do this for new projects, via the git config --global init.templatedir command, but I have a lot of pre-existing git projects that I wanted to add a pre-push hook to, and I wanted to be able to make alterations to this hook after the fact that would affect all my projects. Apparently, I'm not the only person who needed this feature, because it was added in git release 2.9.

Details

Adding the global hooks was easy enough, thanks to this stackoverflow answer, but I did run into a couple of caveats after I had the global hooks path set.

git config

To add the path to your global git configuration run the following command:

git config --global core.hooksPath /path/to/my/centralized/hooks

Hook file

The next step is to add your hook file and make it executable.

touch /path/to/my/centralized/hooks/pre-push
chmod a+x /path/to/my/centralized/hooks/pre-push

And then add what ever logic you'd like the hook to execute. I use sonarqube to provide Continuos Inspection to my projects, so I wanted the sonar-scanner to run on every push. (I highly recommend sonarqube for keeping bugs and code smells out, you should check it out if you're not familiar with it!). I use the fish shell, so you might need a different shebang.

# /path/to/my/centralized/hooks/pre-push
#! /usr/bin/fish

command sonar-scanner

So I created my hook and did a test push, to see that it worked as expected. However, I do have some documentation only and small script projects that don't use the sonar-scanner. I was getting some ugly error messages when pushing these projects. It didn't fail the push, because I wasn't checking the return code on sonar-scanner command, but I still wanted to silence these messages, or not run sonar-scanner at all on projects that didn't need it. That was easy enough to do by checking for the presence of the sonar-project.properties file before running the scanner.

# /path/to/my/centralized/hooks/pre-push
#! /usr/bin/fish
if test -e ./sonar-project.properties
    command sonar-scanner
end

Ok, so now that is running only when it should, but I bumped into another issue. I had some projects that had project specific pre-push hooks that I expected to still be running before a push was executed. I had assumed that adding these global hooks would be in addition to the project hooks, not overriding them. However, that is not the behavior I was wanting; I still wanted any project specific hooks to be executed. The fix for this was to check for the existence of a project level git hook and fire it if it exists. I decided it would make more sense for my use case to fire it before the global hook logic was executed.

# /path/to/my/centralized/hooks/pre-push
#! /usr/bin/fish

if test -e ./.git/hooks/pre-push
    command sh ./.git/hooks/pre-push
end

if test -e ./sonar-project.properties
    command sonar-scanner
end

Conclusion

So there I had my global hook, that only ran the sonar-scanner if it was necessary and made sure to also execute any local hooks. I'm sure I've only scratched the surface of the power of this, and I'm looking forward to adding more functionality in the very near future. I'm going to investigate failing the push if the sonarqube quality gate fails, next. To improve my CI/CD work flow. Have any suggestions or ideas for better hooks? Please leave them in the comments below.

DEV Community: Todd Eidson

Alphabetize your Way to More Readable Code

Alphabetize your Way to More Readable Code

Global Hooks with Git

Global Hooks with Git

Introduction

Details

git config

Hook file

Conclusion