styles

Styles

A collection of style guides and best practices used for my projects and teams.

These styles are meant for humans and agents alike. Agents can use them paired with my brain repo, which covers how my bot team works.

Build License

Tooling Configuration

Configuration files for styling and formatting tools across languages live in the src directory.

NPM Install

npm install --save-dev justintime50-styles

Composer Install

composer require --dev justintime50/styles

General

Architecture

Checklist

Classes

Comments

Concurrency

Databases

Documentation

Error Handling

Functions

Proper Function Structure

Functions should follow the 1-2-3 principle:

  1. The first grouping of code (split by an empty newline) is usually boilerplate code or setup where we assign variables that we’ll need later on
  2. The second grouping of code (split by an empty newline) is the logic where we actually do what the function is called
  3. The third grouping (split by an empty newline) should be the final return statement. Functions should also only return once at the end for easy maintenance and readability

There are obviously larger and smaller functions than this, but don’t be afraid of newlines in functions. I’ve seen countless 30 line functions that had no line breaks which can be very hard on the eyes when scanning or reasoning about code. Breaking up related blocks of code makes maintaining and reading that code much easier.

def is_number_large(my_number, threshold = 100):
    """Returns true if a number is larger than a custom threshold."""
    number_as_int = int(my_number)
    threshold_as_int = int(threshold)

    if number_as_int > threshold_as_int:
        large_number = True
    else:
        large_number = False

    return large_number

Git

Meta

Naming

Reviews

Testing

Versioning

Language Specific

CSharp

CSharp Tools

CSS

CSS Tools

CSS Styles

The following is a checklist of items that every website should have:

Docker

Docker Tools

Golang

Golang Tools

HTML

HTML Tools

HTML Styles

The following is a checklist of items that every website should have:

Java

Java Tools

JavaScript

JavaScript Tools

PHP

PHP Tools

Python

Python Tools

Python Styles

It’s generally an anti-pattern to do something like the following. If a file got deleted between the check and it being removed, it will error:

# Anti-pattern
if os.path.isfile(file_path):
    os.remove(file_path)

# Use instead
try:
    os.remove(file_path)
except FileNotFoundError:
    pass

Ensure that error assertions are unindented from a pytest context helper (bites me all the time):

# This will fail
with pytest.raises(Error) as error:
    my_function('BAD_INPUT')

    assert str(error.value) == 'You sent bad input'

# This will succeed
with pytest.raises(Error) as error:
    my_function('BAD_INPUT')

assert str(error.value) == 'You sent bad input'

Ruby

Ruby Tools

Shell

Shell Tools

Shell Styles

Swift

Swift Tools

Websites & Infrastructure

Websites & Infrastructure Styles