johnmcfarlane

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

johnmcfarlane

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

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

johnmcfarlane

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

johnmcfarlane

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.

grepability

grepability is the quality that:

johnmcfarlane

{
  // 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",

johnmcfarlane

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

johnmcfarlane

===-------------------------------------------------------------------------===
                          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

johnmcfarlane

# 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

johnmcfarlane

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.

johnmcfarlane

--2020-06-01 14:46:28--  http://upload.cppreference.com/mwiki/images/f/f8/cppreference-doxygen-web.tag.xml
Resolving upload.cppreference.com (upload.cppreference.com)... 2604:4f00::3:0:1238:1, 74.114.90.46
Connecting to upload.cppreference.com (upload.cppreference.com)|2604:4f00::3:0:1238:1|:80... connected.
HTTP request sent, awaiting response... 200 OK
Length: 1100140 (1.0M) [application/xml]
Saving to: ‘cppreference-doxygen-web.tag.xml’

cppreference-doxygen-web.tag.xml                     100%[=====================================================================================================================>]   1.05M   853KB/s    in 1.3s    

2020-06-01 14:46:30 (853 KB/s) - ‘cppreference-doxygen-web.tag.xml’ saved [1100140/1100140]