How did I run that code again? Tools to help recall

[iandanforth]

The 'actively displayed documentation upon project entry' seemed the most useful tip.

In the physical world or in GUIs if there's a concise bit of large text in front of you it can be hard to ignore. But the command line is a barren wasteland until you take action. This tip basically brings what the author sees as a minimal documentation / GUI to every project via a command that they run by habit now upon project entry.

There's also a good point that documentation is a PITA and so you should try to make a doc generating tool that extracts the most critical info you need to use a given project from the code itself so you don't have to repeat yourself. The author determined that aliases set in the project are such critical info for example.

I think it would be fun to write a 'universal' `help` tool that took some of these heuristics and tried to produce minimal docs from any directory that was discernibly part of a coding project. Delightfully open-ended and unsolvable, probably needs some machine learning sprinkled on top as well.

[egberts1]

I got whacked again into reading from the smallest portal window to the main body of the article.

On my iPhone Firefox screen real estate, nearly 2/3rd were taken over by website’s navigation area (or is that the floating outline index of the article itself?).

Despite that challenge, I doggingly read on with the main portal that mainly and underwhelming overtook 1/4th the screen.

Good article. Hell of a website although.

[MisterSandman]

Broken on Chrome on Android for me, too. A weird mix of forced-desktop and mobile weirdness going on.

[whacked_new]

Valid criticism, agreed, and thanks. I'll be fixing that soon, apologize for the inflicted suffering, but hope on balance it was good!

[zelphirkalt]

My favorite tool for remembering how to run something, or rather for not having to remember: A simple Makefile and a readme file.

[dividedbyzero]

I've been using make to do this for ages, but its syntax really shows its age in a bad way. A while ago I switched to just (https://github.com/casey/just), which is a simple command runner with less unnecessary cruft (for my use case as a command runner) and a much saner syntax, and I've been pretty happy with it so far, I hardly ever need to look up anything.

There's also task (https://taskfile.dev/), which is YAML-based and might work well in an environment where everything else is YAML anyway, and makesure (https://github.com/xonixx/makesure), which is pretty similar to just, but didn't really click with me.

[theshrike79]

Regardless of the language I use for a project I always have these:

  - make test
  - make build (or run if it's an interactive app)
  - make publish

Publish runs test + build and uploads it to "production".

For Go projects I've started to move to Magefiles though: https://magefile.org

[silves89]

I grew frustrated with the compromises of makefiles for this and over the years I wrote a couple of alternatives, run_lib[1] and lk[2]. Now I write files full of the bash functions I need and use lk to explore and execute them. I.e. it's a consistent interface accross projects.

[1] https://github.com/jamescoleuk/lk

[2] https://github.com/jamescoleuk/run_lib

[dylanowen]

Same here, I have a makefile in every project.

[tqwhite]

I wrote an entire essay about this at https://tech.genericwhite.com/remembering-details-of-program... but here is the gist...

The main things I have figured out are, 1) use a script to contain all the stuff I know I will not remember, 2) structure projects so that there is a script for each environment I have to work on, 3) be rigorous in making all that structure the same because I know I will not remember where the script is if it's different, 4) use aliases (also, btw, listed in my .bash_profile) to execute them so I am not confused and 5) make sure to write all the fussy details in those scripts and keep them up to date and refactored frequently.

[nicbou]

I echo a similar sentiment: https://nicolasbouliane.com/blog/no-script-is-too-simple

If you can't run your project without pouring through documentation, you need to fix that. Projects should be easy to get back into after a long absence. In a business, it makes onboarding cheap and easy.

[codethief]

I cannot agree enough. Items 1 and 5 especially are worth reiterating: How to run/test/build things should be entirely documented in terms of code, not README files, unless there is no other way. README instructions become outdated quickly and are hard to test in a reproducible manner.

IMO, every project should have one single CLI presenting the developer with everything she or he can do (pull or update dependencies, build, run, test, …). Just like applications come with a UI for the user (whether the user is a real person or just some other application), every project should have a proper user interface for the developer.

[whacked_new]

We're generally in agreement, and at the risk of exposing my biases... nevermind, my biases are already exposed -- I discovered that wrapping the aliases inside a shell.nix expression to be activated by running `nix-shell` has the added benefit of locking down the execution environment down to the compiler version.

The most illuminating experience for me was doing this for a Python 2.7 project, cloning the repo, running nix-shell, and it Just Worked. I was shocked (in a good way)

[3pt14159]

lol, are you me? Only thing you didn't mention is the importance of .git/info/exclude so my custom scripts don't distract me on a git diff.

[tokamak-teapot]

I make a script called 'run' in the root dir of everything that can be run. Sometimes it's just 'make && ./foo', but it's the easiest way I have to remind myself

[kerneloftruth]

I create a file cmds.txt in project directories which contain lists of any commands I might typically use (especially in the context of the directory where I place it). That way, I can 'find . cmds.txt' to recall. Low tech and brain dead simple, but it works for me.

[swah]

Me too, but sometimes there are multiple commands to remember in the same root.

[jrib]

README is the only universal thing that can be counted on across languages / toolchains / frameworks / whatever. I try to script as much as possible but if I don't put a pointer to it in the README, my future self will be frustrated.

[tqwhite]

I use BASH scripts, even to manage Windows server projects. It's close enough to universal. (I hate WSL but it's better than the alternative.) I make aliases for everything. It totally works.

I explain my strategy here: https://tech.genericwhite.com/remembering-details-of-program...

[swah]

And if you push it to GitHub/Lab, it will be there for everyone that arrives, nicely rendered.

[JamesSwift]

Make works just fine across everything I've ever tried

[whacked_new]

OP of the article here. The content here is hosted in a little app meant to experiment with an alternative kind of commenting model where all comments are pull requests. I don't know how well it works.

Feedback welcome.

[swashbuck1r]

Some raw feedback: It’s impossible to read on my iPhone. All content ends up in the far left quarter-column of my screen. I can’t zoom to see the content in that column (a default behavior for most sites). Switching to “reader” mode (to remove all the stying tricks) seems to show content that is not related to the article I was trying to read. I’ve rarely seen a site wreck an iPhone safari browser that badly :) - I’m interested in the topic though, so will try to remember to look when at a full-size browser.

[kwertyoowiyop]

On my iPad, the Contents took up most of the screen, and confused me because I expected them to automatically minimize when I scrolled down. Maybe start the Contents minimized?

[rgoulter]

I'm glad to see nix mentioned.

It's maybe a little too weird to be able to practically recommend generally. (It's very difficult to deal with unhappy cases; you really need to know what you're doing to work through those). But, the promise of being able to have a development environment made available with a single command by having declared the programs a package is built with is really neat.

[JamesSwift]

Not only great for a dev shell, but also has a killer feature in nix-shell shebangs. So I can fully encapsulate requirements of a helper script in the file itself, and not dirty the local system with, for example, `jq` just because I want to parse JSON.

[unfocussed_mike]

"If there's one prediction I'm really really good at making, it's the prediction that future me is not going to remember."

Yep.

[SomeHacker44]

history | tail -100 >how-to-WHATEVER_I_JUST_DID.txt

[dhimes]

Wow, I never thought of this. I usually write a bash script.

[hinkley]

The problem I always have is that when a problem is pointy enough, I figure out how to solve it once and for all. Then I don’t have to think about if for three years.

What happens is that I spend almost all of my time and energy on third tier priorities and problems because I’m a coder, and if things have clear cause and effect I’m going to automate that shit the first time it pisses me off or embarrasses me or a peer.

The longer I’m on a project the more bimodal is my set of focuses. Really big picture, and niggling little minutiae. God knows what it’s like for someone interviewing me and asking about my last gig.

[luxurytent]

At our startup, things are still being shaped so there's not a slick development experience.

We have robust documentation and we've practiced engineers maintaining a "stash" repo for their notes, which may sync back up to the primary documentation. We also make an effort wipe our stack and redo it every 2-4 weeks, so that we understand the warts while potentially finding new ones.

We'll slowly move towards better developer experiences (and Makefiles are honestly great for most use cases), but a documentation culture is most important right now.

[tenken]

I have done all of these things.

The last time I did this, I wrote a self documenting bash script project.sh similar to the last Nix example with a list of commands and a help text and menu options.

Another useful object is not just unix history but a tool like Rash in Python, advanced bash shell history stored in SQLite. There are many similar tools nowadays but then you can look for commands you run in this project directory structure in your cli history. Projects are not flat, so there may be specific commands needed in certain directories.

[erwincoumans]

I appreciate it a lot when a software project makes it easier to build and execute the program. So much time lost trying to figure it out, over and over again by others but also yourself. For some of my own projects, I embed required resources such as shaders and fonts, directly into the executable, to avoid having to point to the path/directory to find them. cmake build working out-of-the-box, by reducing dependencies, or making them optional.

[sigmonsays]

one of my favorite patterns is to put a makefile in the top level directory

the first target is 'help', so when you enter the directory, you run make and it spits out a list of possible targets.. The help target is just a bunch of #comments.

Each target does some sort of useful thing, like regenerating swagger, cleaning up temporary crap, starting in dev mode, etc.

Coupled with a readme it's the best, simplest approach.

[khimaros]

make also has tab completion

[tivolian]

This is a pretty basic question, but what kind of projects would I want to use nix for? At what level do projects become complex enough that it's helpful to add this additional tool on top of whatever I'm using already?

[CraigJPerry]

I’ve worked in a few places that standardised how to build, test and run all projects. Regardless of language or runtime platform. In my experience there’s a significant number of developers who just don’t see any value in this.

[JamesSwift]

My set of tools is make, docker/nix, and a README

[suyash]

I prefer the simplicity of README for this purpose.

[InfiniteRand]

Has anyone tried recording everything they do all day on the computer and then reviewing it when they have questions?

[dottedmag]

I have a shell history with the limit of 1M lines, and shells append to it, not overwrite it on exit.

I never have to review (except occasional grep something ~/.zsh_history), but I find myself typing Ctrl-R to find commands in history all the time.

[lambdaba]

I have not tried it but this is where an enhanced shell history (particularly with cwd) might come in handy: https://github.com/ellie/atuin

[dplgk]

If I'm working on something pretty tedious, I'll record a screen capture explaining what I was doing and where I left off.

[tqwhite]

As someone above said,

history | grep -i "whatever I want to remember"