Skip to content

Practicalli Articlesλ︎

Advantages of writing documentation for code

Code that executes correctly and provides only limited value to the business can still be a huge maintenance burden.

Code is very rarely written to include why is was added, what is the purpose of this code.

Dismiss the value of adding documentation that describes the why of the code significantly increases the cost of maintaining and extending that code. Skipping documentation adds to the engineering debt of any solution (even when the intention is to re-write that code).

  • in clojure
  • 6 min read

Essential tooling for Clojure development

alternative text

Clojure development benefits from great tooling focused around an editor.

Autocomplete, refactor tools, diagnostics feedback and syntax highlighting enhance the creation and modification of code.

Evaluating in source code and using data inspectors for the results provides an effective interaction with the REPL.

Practicalli encourages editors that provide user actions driven exclusively via the keyboard and an uncluttered user interface.

Practicalli Clojure provides an overview of Clojure editors and the plugins that provide Clojure support, e.g. Emacs, Neovim, VS Code, Pulsar and Sublime.

Practicalli preferred editors

LightTable was the editor used in the early years of learning Clojure as it was simple to use and provided instant feedback as code was typed.

Once Spacemacs was release, Emacs with CIDER became the predominant editor for many years.

Treemacs and LSP have matured so Neovim and Conjure has been adopted to provide a fast editing environment with streamlined key bindings for Clojure development.

  • in git
  • 5 min read

Safeguard against Git Commit Spoofing

alternative text

Git Commit Spoofing is where a person uses the Git identity of another person to modify commits pushed to GitHub, assuming they can obtain write permission to a branch or via a PR.

Signing is especially useful for those contributing changes via a pull request. Signing provides greater confidence that the contribution is from a verifyable account.

Working in the Financial sector for many years, signing of commits has become manditory to reduce risk and increase traceability for audit trails.

All Practicalli commits are now signed using a passphrase protected SSH key, registered as a signing key with the GitHub account. All contributions via pull request should be also be signed, either with GPG or SSH keys.

  • in emacs
  • 9 min read

Build Emacs from source on Debian Linux

Practicalli Emacs Logo

Emacs 29 is the current stable release, adding major features: Eglot LSP client, Tree-Sitter language parser and package.el package install from Git repositories.

Building from source is a convenient way to try Emacs features in advance, especially useful for those maintaining or developing new tools on top of Emacs.

Emacs 29 Features

Emacs 29 - what to expect - a brief summary of the major features

  • in clojure
  • 5 min read

Expose Clojure Service using Ngrok

Practicalli Clojure Logo

Exposing a local running services can be valuable when writing apps and web-hooks for Cloud API products, e.g. Slack, Atlassian Confluence, Hasura, Salesforce, etc.

ngrok exposes local networked services behinds NATs and firewalls to the public internet over a secure tunnel.

Create a free ngrok account to get an authorisation token for use with the ngrok agent to create a secure tunnel. Or add an SSH public key to use SSH reverse tunnel with the ngrok service.

  • in emacs
  • 3 min read

Pin Emacs packages to manage issues

Practicalli Clojure Logo

Emacs provides a huge amount of features via packages. Community configurations like Spacmacs orchestrate packages so they work seemlessly together. It is rare, but sometimes a package will have a breaking issue.

Melpa provides (5,544) up-to-date packages automatically built from each projects Git repository. Builds are defined by a recipe for each package.

A custom recipe can be used to control which version of a package is used with the Emacs configuration, to work around issues or changes to a package.

  • 9 min read

Accessing AWS with Clojure from scratch - simple approach

Practicalli AWS topic logo

Cognitect Labs AWS API is an excellent data driven Clojure library for interacting with AWS from code. The project includes working code examples.

The biggest challenge for those new to AWS is to configuring suitable AWS accounts, programmatic access and service permissions.

This article starts with nothing and steps through the simplest and quickest AWS account and permission setup, using the 🌐 AWS Free Tier.

Service quota limits

Each service has itos own quota limits and some services are only free for a period of time (free trials & 12 months free).

The approach outlined is not intended for commercial work, only the bare essentials to start exploring what is possible with the Cognitect Labs library. Or try 🌐 LocalStack if docker is installed locally.

  • in docker
  • 7 min read

Docker: a simple workflow for Clojure

Practicalli Clojure Logo

Docker enables a consistent approach to building and running Clojure projects along with a range of other services locally (database, cache, streams, etc.), The Clojure project is built from source when starting services (a watch feature can rebuild on code changes). Heath checks and conditions are set to ensure dependant services start in the correct order.

Running Docker is relatively fast once image overlays (layers) are cached on their first run, so its a viable approach for local system integration testing and acceptance testing, before pushing changes to a remote Continuous Integration service.

A Docker workflow complements a REPL Driven Development workflow, it does not replace it. The main development effort should be more effective via a REPL connected editor with Docker Compose focused on orchestration of services.

Deeper into Docker

Practicalli Engineering Playbook covers Docker and Compose in more detail

Create deps-new templates for Clojure CLI projects

Practicalli Clojure Logo

Templates are great way to learn how to assemble Clojure libraries into a working project and can save considerable time when creating new projects by providing common configuration, development tools, dependencies and code used by the engineering team.

seancorfield/deps-new provides a simple to understand approach to defining templates. Declarative rules express how file templates are copied to create a new project. Substitution values are passed to {{unique-key}} placeholders in template files creating a specific project each time. Programmatic transformation is also supported for significant customisation, e.g. adding options to templates.

practicalli/project-templates is a new project to provide comprehensive templates to support production level workflows, including Dockerfile configuration, GitHub continuous integration workflows, etc . Read on to see how the first template was built and learn tips to building your own templates.

deps-new provides a guide to writing templates

London Clojurians Community - a relatively brief history

Practicalli Community Logo

The London Clojurian community started in 2009 when Robert Rees tricked Bruce Durling into organsing monthly events. From those humble beginnings the community has grown close to 4,000 members with several monthly events taking place fairly consistently over the last 14 years (5 events in 1 month was the record).

The community has thrived due to the hard work of a great many people and this article probably misses out on a lot of activities (especially in the early years). I would like to thank everyone involved in organising events, hosting events and attending events. Without you there would not be a community.

I steped down as one of the main organisers having delegated all of the work to many other people. The last decade of community work has been very rewarding, but its time for other to continue the work. I now focus on the Practicalli educational websites for learning and using Clojure effectively.