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.
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.
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.
I dont get mage, but i've been using makefiles for over 13 years.
I love go but the only example on the site is bad, and there is not any others. Also, executing commands in go is tedious and verbose w/o helpers. The "Why" on the page fails to convince me as well.
How is a makefile too much whitespace?
Is there any good examples of mage being used in a larger project? preferably a popular one?
If your makefile is mostly just simple single commands, there really is no point in moving to magefiles.
The test/lint/build phases of my magefiles are mostly the same as makefiles. What differs is the publish command:
There I can make use of (for example)native AWS libraries to do complex deployment processes with error checking and validation. All this is of course doable with makefiles, but it gets very tedious compared to a "real" programming language.
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.
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.
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.
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.
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)
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
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.
Me too - but never thought about this good tip with the "find" command.
The article's caveat about storing "just the commands" (run log) applies though..
Something I used to do (many years ago, in my Uni days) was to have a script called wtf in directories with code (and some without). Most of them were no more than a text document wrapped by a #! line and cat <<here-doc so it could be read as a text file too.
The file contained what project or uni module it was for, and any significant commands (build & run one-liners), and links to documentation. Some of them had a couple of extra commands to run those one-liners if given a relevant parameter (such as “./wtf make”), like tokamak-teapot's run command but with a little extra typing. Basically a README that could potentially do a few actiony things.
Not something that I kept up in later life though. It was helpful for just me when I had a significant bunch of things actively going on or being referred back to, and particularly useful when the work was part of a group project or otherwise shared to others.
In order to deal with that in my personal projects and my personal space of my public projects, I keep a central Makefile, separate from any eventual build Makefile that the project may already have, which stores all the commands that I typically use in that directory.
This is not necessarily the best solution, as you have to name even very simple commands, but it's not so hard. What I wished was for bash to have two histories, a global history and a per directory history, so I can look at what commands are typically run in a directory. I hear it is easier to do in zsh, but I have no working solution.
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.
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.
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.
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.
Yeah, guilty as charged, and not acceptable. I don't yet know how to interact with the reader mode, but there's my weekend now. Thanks for the advance feedback and I hope you remember to check back as well :-)
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?
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.
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.
One use case I liked for nix-shell shebangs was having a Python script which used Jinja templates.
By adding a line like `#!nix-shell -i python ...`, it means that I could just run this Python script with "nix-shell generate.py".
It's not that installing jinja itself is hard.. it's just that it's a nicer "Developer Experience" to jump back into the project without having to fiddle with re-installing stuff.
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.
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.
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.
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.
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.
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?
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.
Same for me. Windows PowerShell now conveniently comes with PSReadLine, that enables to just hit on CTRL+R, write some keywords (and maybe after few more CTRL+R hits), and that historical command pops out whenever I need it.
Even better, newer versions support predictions [0] - which, whenever you type any text, it immediately lists multiple commands where it finds a match.
Of course, that addresses only myself, but not whoever touches the project. As well, I may not know in what context that command was ran. So I appreciate some suggestions here that guide toward making scripts and providing useful info in README.
There's also nifty Windows application called Ditto - basically a searchable history of the system clipboard. Any time there's any complex command or a snippet, I intuitively just highlight it (in Putty) or CTRL+C it
Log in to our Postgres? that's `psql` something something. CTRL + ALT + V, type psql - there it is
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.