changelog shortlog graph tags branches changeset files revisions annotate raw help

Mercurial > org > meta / style.org

changeset 5: 6538a100c792
parent: 55e56793d888
child: f747ffac7f40
author: Richard Westhaver <ellis@rwest.io>
date: Sun, 18 Aug 2024 22:16:12 -0400
permissions: -rw-r--r--
description: weekend warrior 
     1 #+title: The Compiler Company Styleguide
     2 #+author: Richard Westhaver
     3 #+email: ellis@rwest.io
     4 #+setupfile: ../clean.theme
     5 #+glossary_sources: glossary.org
     6 As an organization we maintain a styleguide[fn:1] which lists all of
     7 the style guidelines we use for our code. If you are contributing to
     8 one of our projects, you should review and understand the relevant
     9 sections below.
    10 
    11 You should also review the [[file:ulang.org][ulang]] document, which may shine some light
    12 on code comments and developer docs.
    13 
    14 [fn:1] https://google.github.io/styleguide/ 
    15 
    16 * General Programming
    17 :PROPERTIES:
    18 :ID:       5cee979a-3732-45ed-87f5-cadf591cac42
    19 :END:
    20 - indent-offset = 2
    21 - max-line-width = 80
    22 - page-length ~ 32
    23 - module-length ~ 512
    24 - file-size ~ 1024
    25 
    26 - start every source-file with a header comment
    27 - use outline headings to organize your program
    28 - use ulang-comments as needed for referencing bugs, notes, etc.
    29 - inline documentation should be declarative. your code explains your
    30   comments for you.
    31 - variables, imports, and exports belong at the top of a file
    32 - =main= functions belong at the bottom of a file
    33 - use LSP wherever possible (eglot, slime)
    34 * Common Lisp
    35 :PROPERTIES:
    36 :ID:       d4c25810-ce35-411e-a371-67ab7e814260
    37 :END:
    38 - prefer symbol docs to comments
    39 - use stdin/stdout/stderr correctly - see [[https://zenodo.org/records/3414191][CDR-11]]
    40 - always prefer =core= libraries over vendored dependencies
    41 - use the compiler built-ins - if a function or class is generally
    42   useful, add it to the core
    43 - use conditions, restarts, and error handling where appropriate
    44 - save type declarations and hairy optimizations for when the API is
    45   polished
    46 - don't be afraid of macros
    47 ** Systems
    48 :PROPERTIES:
    49 :ID:       2a323c4c-362c-429f-9849-587e2a7311f5
    50 :END:
    51 - define systems using keyword symbols
    52 - use slash instead of dash for path separation in system names: =:foo/bar=
    53 - define your test system in the same file with a name of: =:foo/tests=
    54 - where possible, avoid collisions with systems in Quicklisp
    55 ** Packages
    56 :PROPERTIES:
    57 :ID:       f735b4b5-4818-408b-a244-e2fb506c7ded
    58 :END:
    59 - declare packages in a file named =pkg.lisp=
    60 - when multiple packages are being declared, consider a wrapper
    61   package
    62   - declare with ~UIOP:DEFINE-PACKAGE~ and ~:USE-REEXPORT~
    63 - package names are either the same as their system name or have the
    64   system name as their root path.
    65 - use ~:NICKNAMES~ to declare alternative names for your package
    66 ** CLOS
    67 :PROPERTIES:
    68 :ID:       5068e164-764a-4843-be8f-126754938ef9
    69 :END:
    70 - prefer =:default-initargs= over =:initform=.
    71 * Rust
    72 :PROPERTIES:
    73 :ID:       8e414073-36b6-45d4-9a11-e6de8a0a65e9
    74 :END:
    75 - always prefer =core= libraries to vendored dependencies
    76 - don't make =mod.rs= files
    77   - use the =foo.rs=, =foo/*= pattern instead
    78 - derive =Debug= and =Clone= always
    79 - write a sensible =Display= impl
    80 - derive default methods for =Default=, =Hash=, =Copy=, etc where possible
    81 - use generics where appropriate: =foo<P:AsRef<Path>>(path:P){p.as_ref();}=
    82 * Emacs Lisp
    83 :PROPERTIES:
    84 :ID:       8b17f8a3-74f2-44cd-a5ce-7df540e2544c
    85 :END:
    86 * Org-mode
    87 :PROPERTIES:
    88 :ID:       ea4fa698-7a46-46d6-a7a0-5b497119edf2
    89 :END:
    90 * Shell
    91 :PROPERTIES:
    92 :ID:       10904e36-e4ac-4841-b602-d4dc68a54c71
    93 :END:
    94 * Python
    95 :PROPERTIES:
    96 :ID:       5b402ced-2329-4a16-b512-76859157a9d6
    97 :END: