Practicalli Software Engineering Guides

Advantages of writing documentation for code

Practicalli Johnny — Wed, 16 Apr 2025 23:14:53 +0000

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).

Essential tooling for Clojure development

Practicalli Johnny — Mon, 29 Jan 2024 00:00:00 +0000

{align=right loading=lazy style="width:240px"}

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 :fontawesome-solid-book-open: an overview of Clojure editors and the plugins that provide Clojure support, e.g. Emacs, Neovim, VS Code, Pulsar and Sublime.

??? HINT "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](https://practical.li/neovim/) has been adopted to provide a fast editing environment with streamlined key bindings for Clojure development.

Safeguard against Git Commit Spoofing

Practicalli Johnny — Sat, 20 Jan 2024 00:00:00 +0000

{align=right loading=lazy style="width:240px"}

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.

Build Emacs from source on Debian Linux

Practicalli Johnny — Sat, 21 Oct 2023 00:00:00 +0000

{align=right loading=lazy style="width:240px"}

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.

??? INFO "Emacs 29 Features" Emacs 29 - what to expect - a brief summary of the major features

Expose Clojure Service using Ngrok

Practicalli Johnny — Thu, 24 Aug 2023 00:00:00 +0000

{align=right loading=lazy style="width:240px"}

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.

Pin Emacs packages to manage issues

Practicalli Johnny — Tue, 15 Aug 2023 00:00:00 +0000

{align=right loading=lazy style="width:240px"}

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.

Accessing AWS with Clojure from scratch - simple approach

Wed, 17 May 2023 00:00:00 +0000

{align=right loading=lazy style="width:240px"}

:fontawesome-brands-github: Cognitect Labs AWS API{target=_blank} 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 :globe_with_meridians: AWS Free Tier{target=_blank}.

!!! INFO "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 :globe_with_meridians: LocalStack if docker is installed locally{target=_blank}.

Docker: a simple workflow for Clojure

Practicalli Johnny — Mon, 15 May 2023 00:00:00 +0000

{align=right loading=lazy style="width:240px"}

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 :fontawesome-solid-book-open: REPL Driven Development workflow{target=_blank}, 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.

!!! HINT "Deeper into Docker" :fontawesome-solid-book-open: Practicalli Engineering Playbook{target=_blank} covers Docker and Compose in more detail

Create deps-new templates for Clojure CLI projects

Practicalli Johnny — Thu, 30 Mar 2023 00:00:00 +0000

{align=right loading=lazy style="width:240px"}

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.

:fontawesome-brands-github: 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.

:fontawesome-brands-github: 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 :fontawesome-brands-github: guide to writing templates

London Clojurians Community - a relatively brief history

Practicalli Johnny — Fri, 10 Mar 2023 00:00:00 +0000

{align=right loading=lazy style="width:240px"}

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 :fontawesome-solid-book-open: Practicalli educational websites{target=_blank} for learning and using Clojure effectively.

Build and run Clojure with Multi-stage Dockerfile

Practicalli Johnny — Sun, 30 Oct 2022 00:00:00 +0000

{align=right loading=lazy style="width:240px"}

Deployment of a Clojure service is very simple, requiring only an Uberjar (archive file containing the Clojure Project and Clojure run-time) and the Java Run-time Environment (JRE).

A Clojure service rarely works in isolation and although many services are access via a network connection (defined in Environment Variables), provisioning containers to build and run Clojure along with any other services can be valuable as complexity of the architecture grows.

A Multi-stage Dockerfile is an effective way to build and run Clojure projects in continuous integration pipelines and during local development where multiple services are required for testing.

Docker Hub provides a wide range of images, supporting development, continuous integration and system integration testing.

FreeDesktop.org XDG standard for Clojure development tools

Practicalli Johnny — Mon, 16 May 2022 00:00:00 +0000

{align=right loading=lazy style="width:240px"}

The :globe_with_meridians: FreeDesktop.org XDG basedir standard{target=_blank} defines specific locations to store all user configuration, data files and caches.

Without the XDG standard, these files and directories are often mixed together and stored in the $HOME of the users account, making it more challenging to backup or version control.

Development tools such as NeoVim, Emacs, Clojure CLI and Clojure LSP support the XDG specification, although some tools like Leiningen required a little help. There are simple approaches to work-around the limitations of tools that don't conform.

Building Emacs 28 on Ubuntu Linux

Practicalli Johnny — Mon, 16 May 2022 00:00:00 +0000

{align=right loading=lazy style="width:240px"}

Emacs 28.1 is a feature packed release and includes native compilation to significantly increase the speed of all Emacs software packages installed. This is a very noticeable difference, especially when Emacs is at the center of your developer workflow.

Ubuntu hasn't packaged Emacs 28.1 yet, although its usually straight forward to build Emacs yourself.

Automate Cryogen Clojure blog with GitHub Actions

Practicalli Johnny — Sat, 28 Aug 2021 00:00:00 +0000

{align=right loading=lazy style="width:240px"}

Practicalli uses Cryogen static site generator for its blog website. Cryogen is fast and simple to use thanks to the Clojure EDN file used for configuration.

Cryogen documentation shows how to publish a Cryogen blog to GitHub pages using Git command. The deployment can be automated using GitHub actions, so that a new version of the site is deployed when Pull Requests are merged to the specified branch (or on direct commits to that branch).

Web Scraping with Clojure - Scraping Hacker News

Practicalli Johnny — Fri, 13 Mar 2020 00:00:00 +0000

{align=right loading=lazy style="width:240px"}

Enlive{target=_blank} is a Clojure library that can be used for generating dynamic server-side content as well as scraping websites.

Scraping websites is sometimes required when they do not provide an API. Although Hacker News does have an API, will show how to scrape its website using Enlive's selectors.

Clojure Advent Of Code - a fun way to learn

Practicalli Johnny — Mon, 02 Dec 2019 00:00:00 +0000

{align=right loading=lazy style="width:240px"}

Advent of Code is the annual coding challenge with a festive theme. Each day there is a new challenge in two parts, the first fairly easy the second a little more involved. The challenges are an investment of your time to complete them all, although even trying just a few is enough to help you think in different ways.

Every programming language requires regular practice to maintain your skills. A full time developer role gives you lots of opportunities to practice every day, however, its often focused in around solving problems within a specific business domain, with little time to explore others. The Advent of Code puts you in a different domain, so its great for extending your coding experiences.

Solving challenges in a different language is another great way to extend your experiences, so here are some tips and examples for solving the advent of code in Clojure.

Advent Of Parens 2019 - feast on Clojure this holiday season

Practicalli Johnny — Sun, 01 Dec 2019 00:00:00 +0000

{align=right loading=lazy style="width:240px"}

The holiday season is know for over indulge, so why not stuff your head full of Clojure and functional programming. Its far healthier than the alternatives :)

To help you indulge, Arne from LambdaIsland{target=_blank}, Bobby Towers{target=_blank}, Alexander Oloo{target=_blank} and I are writing a blog post each day as part of the Advent Of Parens 2019 celebration. Every day we plan to publish a short posts that share tips and experiences with functional programming and Clojure.

You can find the articles I am planning to write on the :fontawesome-brands-github: practicalli blog project board{target=_blank}.

While you wait to open these posts each day of December, I am kickstarting your feast of Clojure in this article.

I also encourage you to take some time over the holiday season to practice Clojure

Clojure Advent of Code{target=_blank}
:fontawesome-brands-youtube: Practicalli Clojure study group{target=_blank}

Clojure powered blogging with Cryogen

Practicalli Johnny — Sun, 20 Oct 2019 00:00:00 +0000

{align=right loading=lazy style="width:240px"}

A blog website shouldnt need a complex content management system. A simple and lightweight static website generator can create engaging websites that are simple to manage with Git.

Cryogen is a static site generator written in Clojure, allowing content to be written in either markdown or asciidoc. Posts and pages are configured with Clojure hash-maps to manage the meta-data and layout information for each post.

Cryogen seems very quick to generate a site and a local server can be run to automatically generate an updated website when changes to posts and pages are saved.