• builds and organizes knowledge

• tests explanations about the universe

• systematically,

• objectively,

• transparently,

• and reproducibly.

Otherwise it's not science.

• improve efficiency,

• reduce human error,

• automate the mundane,

• simplify the complex,

• and accelerate research.

But we don't always them effectively.

• Good: spreadsheet

• Better: csv file

• Best: standardized file format, database management system, version control

Formats: csv, YAML, Hierarchical Data Format (HDF), Flexible Image Transport System (FITS), etc.

Management: C++/Python/Fortran APIs, HDF5, Pandas, astropy, etc.

• Good: USB stick

• Better: nightly emails

• Best: remote version control (GitHub, BitBucket, GitLab), remote backup (CrashPlan, Duplicity)

Version Control Systems: svn, hg, git

Hint: tools like git-annex or git-lfs can help you manager large data files

• Good: systematic naming convention

• Better: versioninig storage solution

• Best: local version control

• Good: use git log

• Better: custom log format, git blame

• Best: gitk, git gui blame

Hint: GUIs are great to explore and look around

• Good: manually edit every file

• Better: search and replace in each file

• Best: scripted batch editing with backups

Hint: try a tutorial on BASH, ZSH, Python, or Perl, e.g. the bash lesson by Software Carpentry.

• Good: retype a series of commands from notes

• Better: shell script

• Best: build system

Build system tools: make, docker, cmake, autoconf, automake, etc.

Reference: The Carpentries have an associated Automation and Make lesson

• Good: giant vector holding all numbers

• Better: list of list of numbers

• Best: appropriate powerful data structures

Hint: In C++, learn about structs, unordered_maps, maps, vectors, and (maybe) classes, etc. In Python the power lies in dictionaries, and numpy arrays, and DataFrames when analyzing data.

• Good: single block of procedural code

• Better: separate functions

• Best: small, testable functions that handle well defined tasks, grop into classes

DRY: Don't Repeat Yourself. Code replication is bug proliferation.

KISS: Keep it simple, stupid.

• Good: d1, d2, d3

• Better: x, y, z

• Best: p.x, p.y, p.z, p = Point(x,y,z)

Hint: Prof. Jenny Bryan on Naming Things

• Good: Have consistent style

• Better: Agree with your colleagues on style

• Best: Follow a standard style guide and use a code formatter

Hint: clang-format, Black code formatter for Python

• Good: have readable code

• Better: document what each code unit provides

• Best: document design and purpose of each code unit

Hints: Best practices for writing code comments, Python PEP-8

• Good: don't

• Better: add timing code and optimize identified hot spots

• Best: use a profiler and optimize overall code structure

Tools: Linux perf, hotspot, gprof, igprof, coz, NVIDIA nsight, Python cprofile, line_profiler, snakeviz

Hints: A good algorithm will outperform a locally optimized bad one

• Good: none, hardcoded variables

• Better: plain text input file, line-by-line homemade string parsing

• Best: argument / file parsing library

Formats: Python argparse, libconfig, yaml-cpp, spify, etc.

• Good: show results to experts

• Better: integration testing

• Best: unit test suite, continuous integration

• Good: re-re-read the code

• Better: print statements

• Best: use a linter, a debugger, and a profiler

Tools: cpplint, pyflakes, gdb, lldb, pdb, idb, perf, hotspot, coz, valgrind, kernprof, kcachegrind, cprofile/snakeviz

• Good: fix code

• Better: fix, add an exception

• Best: fix, add an exception, add a test

• Good: single master copy, waiting

• Better: email and patches

• Best: remote version control

• Good: separation of concerns

• Better: shared repository(s)

• Best: peer-reviewed pull requests

Hint: reviewing changes is work, keep them simple, stupid.

• Good: weekly research meetings

• Better: daily conversations, short term goals

• Best: pair programming, issue tracking

• Good: zip file, theory paper

• Better: code repository, theory paper, comments in code, example input file

• Best: code repository, theory paper, automated documentation, example input file, test suite

• Good: paper notes describing model in code

• Better: electronic documentation in code repository

• Best: auto-generated documentation describing code intent and usage

Tools: doxygen, sphinx

• Good: custom formatting, clickable GUI

• Better: plot format templates (Excel, Mathematica)

• Best: scripted plotting, matplotlib, gnuplot, etc.

• Good: Microsoft Word, LibreOffice Write

• Better: Word, Write with track changes

• Best: plain text markup with version control and a makefile

Tools: LaTeX, markdown, restructured text

• Good: "email to request access"

• Better: license file

• Best: license file, citation file, DOI, forkable repository

Example: SpECTRE

• Good: none, internal use only

• Better: online repository, developer email online

• Best: issue tracker, user/developer forum, communication channels, online documentation