John McFarlane johnmcfarlane

The Clonroads of Ennis

Clonroad More, township in South East Ennis
Clonroad Beg, township in South Ennis
Clon Road, road bordering Clonroad Beg and Clonroad More, separates Station Road from Quin Road
Clonroadbeg, road bordering Clonroad Beg and Clonroad More, continuation of Turnpike Road, West of St Flannans
Clon Road, road bordering Clonroad Beg and Clonroad More, South West of St Flannans, continuation of Clonroadbeg
Clonroadmore, house on Clonroad More side of Clonroadbeg
Clonroadbeg, not in Ennis, road to Ballybeg Woods, ~1km from Clonroadbeg
Clon, Irish word for Clone

Essential Principles

Commonly occuring good advice aimed at improving maintainability.

Brevity

Avoid duplication, tautology, repetition, duplication, and saying the same thing over and over in different ways.
Everything (words, statements, comments) should have a clear purpose.

Resources

Project Maintainability

Fail Loud

Errors and bugs should be prominent. If an error can be dealt with by the client code, it's not an error.

`grep`ability

grepability is the quality that:

How to Write a README

Different people have different views about what constitutes a good README document for a software project. I think it should be vehicle for delivery of the bare minimum knowledge necessary to convey why someone might want to use it and how.

Imagine you're a trainee who was given a URL to the GitHub page on your first day. You have only the bare resources needed to run the program, but none of the knowledge about it.

What information would you need? Make certain to add that information:

Brief description of project aimed at somebody who might need it, but hasn't necessarily ever heard of it.
Link to the projects's home. This might be a github.io site, a Confluence page or a wiki.

	#include <algorithm>
	#include <cassert>
	#include <concepts>
	#include <ranges>

	[[nodiscard]] constexpr auto factorial(std::integral auto n) {
	assert(n >= 0);
	if (n == 0) {
	return 1;
	}

	from time import time

	def primes(maximum: int):
	assert(maximum > 0)
	yield 2
	non_primes = 0
	non_prime_bit = 2
	for non_prime_index in range(1, maximum>>1):
	if not non_primes & non_prime_bit:
	number = (non_prime_index << 1) + 1

	{
	// Use IntelliSense to learn about possible attributes.
	// Hover to view descriptions of existing attributes.
	// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
	"version": "0.2.0",
	"configurations": [
	{
	"name": "(gdb) Launch",
	"type": "cppdbg",
	"request": "launch",

	---
	Language: Cpp
	# BasedOnStyle: LLVM
	AccessModifierOffset: -2
	AlignAfterOpenBracket: AlwaysBreak
	AlignConsecutiveMacros: false
	AlignConsecutiveAssignments: false
	AlignConsecutiveDeclarations: false
	AlignEscapedNewlines: DontAlign
	AlignOperands: false

	===-------------------------------------------------------------------------===
	clang-tidy checks profiling
	===-------------------------------------------------------------------------===
	Total Execution Time: 22.5880 seconds (22.5880 wall clock)

	---User Time--- --System Time-- --User+System-- ---Wall Time--- --- Name ---
	1.4755 ( 8.3%) 0.3357 ( 6.8%) 1.8112 ( 8.0%) 1.8092 ( 8.0%) readability-identifier-naming
	0.9903 ( 5.6%) 0.1667 ( 3.4%) 1.1570 ( 5.1%) 1.1552 ( 5.1%) bugprone-reserved-identifier
	0.8855 ( 5.0%) 0.1358 ( 2.8%) 1.0213 ( 4.5%) 1.0212 ( 4.5%) cert-dcl37-c
	0.8815 ( 5.0%) 0.1316 ( 2.7%) 1.0130 ( 4.5%) 1.0132 ( 4.5%) cert-dcl51-cpp

	# Sphinx version: 3.1.0+
	# Python version: 3.8.2 (CPython)
	# Docutils version: 0.16 release
	# Jinja2 version: 2.11.2
	# Last messages:
	# reading sources... [ 40%] file/wide__tag_2is__same__tag__family_8h
	# reading sources... [ 41%] file/wide__tag_2overloads_8h
	# reading sources... [ 41%] file/wide__tag_8h
	# reading sources... [ 41%] file/width_8h
	# reading sources... [ 41%] file/wrap_8h