programmers-proverbs: a rulebook for the wisdom programmers try to teach

The rulebook that keeps the list from becoming advice

The premise is stated in the opening paragraph. Programming and development often teach one wisdom that cannot be attained elsewhere, coding is a way of life and not just a job, and when you are a coder that is a big part of who you are at work and outside of work. The project invites people to put down their wisdom for future generations to see and learn from.

What follows is a section called The Rules, and it is the most instructive part of the repository, because it is about what the collection deliberately refuses to contain.

The first rule is that programming wisdoms are not allowed. These are supposed to be wisdoms and proverbs about life taken from programming. The example given is sharp. A proverb like `Use semantic class names that are easy to read and understand` sounds great for a programmer, but it misses the point of the repo. It can be rewritten as `Write classnames so others can understand the wisdom of your code`, which makes sense outside of coding as well, that is, work and communicate in such a way that others can understand what you mean and the wisdom behind your work.

That is a real editorial criterion rather than a slogan. The test is whether the line still carries its meaning to someone who has never written code, and the rewrite above is the demonstration that the author applies the test seriously rather than waving at it.

The second rule bans quotation: you cannot submit someone else's quotes, only your own ideas, though you are welcome to look up regular, non-programming proverbs and translate them the way the author did with `A deployed MVP is worth two prototyped`.

The third rule is about credit, and it is practical. You are welcome to add a `- by Me` tag after the quote, which ensures that even after the author restructures the readme file you still get credit. The fourth admits that quotes will be removed, and says a `legacy.README.md` will be built out to store any discarded ones.

So the repository is a list with a constitution. That is the design, and it is the difference between a collection and a curated collection.

A small API for the whole list or a random line

There is an API section for people who want to fetch the proverbs rather than read the README, described as a neat little API for getting a list of proverbs or a single proverb.

The endpoints are two URLs, one for everything and one for a single random entry:

All proverbs: http://proverbs-app.antjan.us

Random proverb: http://proverbs-app.antjan.us/random

That is the whole interface, and it is worth being clear about what it is for. The random endpoint is the interesting one, because a random aphorism is the form that travels. A proverb list is a resource you browse, but a single random line is something you can drop into a chat, a slide or a commit message, and an endpoint that returns one at a time is a machine for producing that.

Two things are worth noting about the deployment. The service is plain HTTP on a personal domain, with no TLS and no versioned path, and the project asks people to tweet the author if they use it so he can see it in action, which is a small request and also a hint about the scale of expected use.

The practical caution is that this is one person's small service on one domain, with no stated uptime commitment, no versioned contract and no error handling described. If you build anything on top of it, you are depending on a hobby service staying up, and you would want a fallback. Fetching the list once and caching it locally is the safer pattern, and the random endpoint is the one that will hurt when it goes away, because the value of it is the surprise.

It is also worth being clear that the API is a convenience rather than an interface anyone needs. The entire content of the project is a README, so the top level of the repository contains README.md and nothing else. The API returns the same text you could read by scrolling.

The recurring theme is the gap between the plan and the work

Reading the entries as a set reveals what they are actually about, which is more useful than quoting any one of them.

A large share of the list is about the mismatch between what people say and what happens. `Just ship` is no substitute for design. `A deployed MVP is worth two prototyped` inverts the usual deployment advice. `Scope creep makes a mountain`. `More hours worked, more commits made. Mostly reverts and bug-causing features`. `Mañana often has the most tickets`. `Today's fashion is tomorrow's legacy`. Each of these is a single sentence that names a specific failure of estimation or of optimism, and each of them lands because the metaphor came from a real practice rather than from a fable.

A second group is about the work habits that make the rest survivable. `Sleep on a force push`. `Don't commit on master when drunk`. `Testing is easier than debugging`. `Simpler code has less bugs`. `Lock up your dependency versions and other valuables`. `Never optimize before measuring`. `What happens in Git stays in Git`. These are the lines that belong on a poster in a team room, and they are also the ones most likely to already be in your head.

A third group is about status and perception, which is the least comfortable subject in the list. `A well spoken developer can be hired hastily but at the last minute fail an easy test`. `A soft spoken developer will see his warnings of technical debt unheeded, and will suffer the blame`. `The better job you do, the easier others discount the level of difficulty`. `A marketer is not a QA, a developer does not advertise`. These are recognitions of a specific workplace dynamic, and they are the reason the collection exists at all, because a proverb about the politics of a codebase is a different object from a tip about a codebase.

There is also a strand of the opposite, about the limits of architecture and design. `If a system works perfectly, no one will care what is inside it. Once it breaks, systems design and architecture decides your fate`. `Leave architecture for applications that require long-term support`. `Architecture and design are preparations for problems and changes, not a key to runtime`. `Without a prototype, don't build a final product`. And a strand about the health of the work itself, `Good test coverage + automated workflows = quiet cell phones and better sleep`, `Deploying an unmonitored app is like going on a roadtrip without a gas gauge`, `A developer that codes until burnout, lives without a mind`.

A handful are attributed, like the line about teaching a programmer to debug so he can do his work for a lifetime, which is credited to Chirag Gude. Others are recognisable adaptations of older sayings, `Facebook wasn't built in a day`, `Absence is beauty, in error logs`, `Eternal sunshine of the stateless mind`, `A git pull a day, keeps the doctor away`.

Why a proverb list resists becoming documentation

The obvious criticism of this project is that it is a list of things you already believe, formatted for sharing, and that adds nothing a team cannot get by writing its own principles. That criticism is largely correct, and the project is not trying to be a principles document.

Look at what the rules exclude. No programming tips, no code idioms, nothing that only makes sense inside a codebase. The author explicitly gives up the most useful-looking content, the actionable advice, in exchange for the content that survives being said out of context. A proverb about life has to be true without a diff, a test or a ticket, and that constraint is what makes the collection a collection rather than a tips list.

The other thing the format does is make the entries quotable in a way that advice is not. A principle document says what your team believes and why. A proverb says one thing, well, and can be repeated by someone who did not read your document. The trade is that the proverb carries none of the reasoning, which is why the rulebook exists to keep the entries from drifting into tips and why the credit tag exists so that a contributor can still be identified after the file is restructured.

There is also a self-referential quality in the collection, which is either charming or circular depending on your mood. `One thing should never do more than one thing`. `Figure out your data structures, and the code will follow`. `The best code is no code at all`. `The best request is the one you don't make`. `If a system works perfectly, no one will care what is inside it`. `A developer will spot a peer from far away`. `A poor programmer blames the language`. `The more technology you learn, the more you realize how little you know`. These are not advice about code, they are observations about the work, and they are the reason the repository exists rather than a list of tips.

The weakness of the format is the same weakness as the format's strength. A line without an argument cannot be argued with, which means a team cannot use it to settle a disagreement. It is a way to name something the team already suspects, not a way to decide it.

A text repository, and what maintenance means for it

The repository contains exactly one file, README.md, and there is no build, no test suite, no CI configuration and no package manifest. The primary language is not classified, which is the honest answer for a Markdown document, and the licence is not one GitHub could classify either.

For a project like this, maintenance is a content problem rather than a code problem, and the rulebook describes the process. The author writes that given the number of pull requests and submissions he received, he wanted to write down a quick FAQ and rulebook, which is the whole editorial policy in one sentence. Discarded quotes go into a `legacy.README.md` that the project says he will build out, so the history of the collection is not lost when the list is pruned.

The last push was on 2026-08-10, the repository is not archived, and there are no GitHub releases. The list grows by pull request, which means the growth rate is a function of how many people are annoyed enough to submit one, and the pruning is a function of how many people submit something that fails the first rule.

The open question the repository does not answer is where the boundary is between a proverb and a platitude. `A hundred programmers won't make a two-year project in a week` and `Facebook wasn't built in a day` are both doing the same work, and the second is the older and more worn of the two, but it survives because the criterion is not originality but whether the line generalises. The rule about translating existing proverbs rather than quoting them is what keeps that boundary from collapsing entirely.

One practical note about the API's durability. The project asks users to tweet the author if they use it, which is a good way to keep a hobby service alive, and the endpoint returns plain text over HTTP with no versioned contract. If you want the list to survive in your own tooling, copy it into your own repository once, and treat the random endpoint as a convenience rather than a dependency.

Editorial conclusion

Adopt programmers-proverbs as a reference for the phrasing you already half-believe, not as a source of new positions, because the whole list is a set of short claims with no argument attached. Do not treat it as guidance you can cite, since the entries carry no authority and the repository is a single README with no tests, and check first that the API still answers, since it is a small personal service on a personal domain and the project states no availability guarantee for it.

Frequently asked questions

Official sources

1. AntJanus/programmers-proverbs on GitHub
2. Issues
3. README