OpsConfig

[OpsConfig @OpsConfig]

Every time someone posts something like the sentiment below I still find myself coming back to Jef Raskin's (employee #31 @Apple ) classic essay "Comments are more important than code."

It certainly reads a little different in the age of AI, but the value remains.

In this essay I take what might seem a paradoxical position. I endorse the techniques that some programmers claim make code self-documenting and encourage the development of programs that do “automatic documentation.” Yet I also contend that these methods cannot provide the documentation necessary for reliable and maintainable code. They are only a rough aid, and even then help with only one or two aspects of documentation—not including the most important ones.

Enforcing excellence in documentation of code is on the frontier of unsolved problems in the management of software development. Some of the solutions seem effective, but they are not yet in the culture of programming or programming education. Rare is the programming teacher who will downgrade a properly performing program because of inadequate documentation.

I discard the radical position taken by proponents of extreme programming (XP) to get rid of “unnecessary” documentation. To some programmers, asking for any documentation is seen as an impediment to getting the “real work” done. XP in general is nicely skewered by Matt Stephens and Doug Rosenberg in Extreme Programming Refactored: The Case Against XP (Apress, 2003).

When programmers speak of “self-documenting code,” they mean that you should use techniques such as clear and understandable variable names. Instead of n or count, it is better to use a readable, self-explanatory name such as numberOfApricotsPickedToDate. This is a minimalist’s documentation. Nonetheless, it helps—the use of explanatory names, whether of variables, modules, objects, or programs, should be encouraged.

In-line comments are problematical, often useless:

t(i) <= t(i) + 13 /* Add 13 to the ith element of t */

But their real problem is their forced brevity. The impulse to toss off a comment quickly is enhanced when the language syntax forces the programmer to be curt: such comments are confined to a portion of one line. When indentation is deep, it can be a small portion indeed:

blix.VK(tofu.haha.cogau) & 00110011B /* mask */

Many become so laconic that you have to understand the code to be able to interpret the comment. Such comments often get further truncated or lost altogether as the program continues to be written or is updated. They are, therefore, also a maintenance headache.

I do not use in-line comments, and I discourage their use by programmers who work with me. If you are going to write a comment, give yourself at least a full line. Or, better yet, give yourself as much space as you need. Some development environments confine comments to a single line. If you wish to make a multiline comment, you have to represent it as a set of single lines. This means that there is no word wrap—to say nothing of many other features that the simplest note-taking software provides. You want to change the comment? You will have to adjust all the line lengths by hand. This is punitive, discourages documentation, and should go where GOTOs went.

Any language or system that does not allow full flowing and arbitrarily long comments is seriously behind the times. That we use escape characters to “escape” from code to comment is backwards. Ideally, comment should be the default, with a way to signal the occasional lines of code.

Automatic documentation generators create flow charts, inheritance diagrams, tables of contents, indexes, topic lists, cross-references, and context-sensitive help entries. One advertised itself as being able “to automatically and continuously update all aspects of the source code documentation, so that the entire team has all the necessary information at their fingertips. Using the information stored in the dictionary and the source files [it] can automatically generate source code documentation.”

The obvious problem is that they do it quite badly. As anybody who has done good documentation knows, generating even an index is not a straightforward, automatic task. The less obvious problem is that many coders feel that once they’ve run the documentation builder over their code, they have documented it. This is the same as the common syndrome of assuming that a document is spelled correctly once the spelling checker no longer flags any words. If you get such “documentation” with a program and find it far from adequate, remember that “eye tolled ewe sew.”

But the fundamental reason code cannot ever be self-documenting and automatic documentation generators can’t create what is needed is that they can’t explain why the program is being written, and the rationale for choosing this or that method. They cannot discuss the reasons certain alternative approaches were taken. For example:

:Comment: A binary search turned out to be slower than the Boyer-Moore algorithm for the data sets of interest, thus we have used the more complex, but faster method even though this problem does not at first seem amenable to a string search technique. :End Comment:

This comment not only names the technique used, but also explains why a simpler approach was not taken.

Good documentation should be readable on its own, with bits of code showing how the design is implemented (and making it run, of course). Reconstructing code from good documentation is far easier than trying to create documentation given the code. Indeed, it is impossible to take code and create the documentation that should have been written as the code was being developed.

Donald Knuth’s work is gospel (except for his writing on religion) for all serious programmers. His essay “Literate Programming” (Computer Journal, May 1984; reprinted in Knuth, D. CSLI Lecture Notes 27: Literate Programming, Stanford, 1992) is must reading. I do not think we need all of his mechanism, but the essential concept of writing the documentation first, creating the methods in natural language, and describing the thinking behind them is a key to high-quality commercial programming. I emphasize commercial because we all know the high cost of customer dissatisfaction and the even higher cost of handling avoidable customer calls. The use of internal documentation is one of the most-overlooked ways of improving software and speeding implementation.

An example of the kind of documentation I speak of appears as part of an interview I did for Susan Lammers’s Programmers at Work: Interviews (Microsoft Press, 1986). The caption reads, “This program demonstrates how Raskin embeds executable code into text that is produced by a word processor.” It is also an example of using an escape method for the code instead of the comments.

It is important not to be doctrinaire about this. I can imagine a programming manager reading this and Knuth, and saying “The answer to my problems!” and mandating that all work be done this way. As Frederick Brooks tells us in The Mythical Man-Month (Addison Wesley, 1995), “There is no silver bullet.” A competent programmer who has learned the documentation-first style will sometimes think of a solution in terms of code, write that first, and then document, or will apply a mixed strategy—especially when no convoluted algorithm design is involved. This should not be discouraged so long as the programmer generally adheres to (and sincerely supports) the documentation-first approach.

Do not believe any programmer, manager, or salesperson who claims that code can be self-documenting or automatically documented. It ain’t so. Good documentation includes background and decision information that cannot be derived from the code. It is hard to imagine any foreseeable software or robot that could collect this information from the people involved with a programming project—at the very least it must understand natural language, which is still the Holy Grail to the AI community.

Prior, clear, and extensive documentation is a key element in creating software that can survive and adapt. Documenting to high standards will decrease development time, result in better work, and improve the bottom line. It’s hard to ask for more than that from any technique.

Source: https://t.co/9ekIyh9gge

[Matt Pocock @mattpocockuk]

1. Delete the docs you create to explain your code

2. Take the tokens you save on updating those docs

3. Spend them on making your code self-explanatory

[OpsConfig @OpsConfig]

@elder_plinius I was very entertained when a week ago Fable helpfully sidestepped gpt-5.5 safety filters for me with:

[Luke Metro @luke_metro]

Muse Spark 1.1 is trained on the screen recordings of Meta employees, which makes it best-in-class at applying for jobs at Anthropic

[OpsConfig @OpsConfig]

Some days I have to double-check to make sure something is real:

https://t.co/HeBlaNAQHG

[the tiny corp @__tinygrad__]

Today, if you were writing a bunch of kernels, what would you reach for? Raw CUDA? tile-lang? Triton? ThunderKittens?

[Joe Weisenthal @TheStalwart]

This is cool

[OpsConfig @OpsConfig]

@TheStalwart I was curious so I onboarded GLM-5.2 and Opus 4.8 to a chess eval app I have been working on:

https://t.co/cOaTy23AN8

I am passing board position and legal moves at each turn, but you still get a sense of the model's relative capabilities.

[JFPuget 🇫🇷🇺🇦🇨🇦🇬🇱 @JFPuget]

@NielsRogge @OfirPress Contamination, irrelevant numbers.

https://t.co/uQsSpjMtPf
https://t.co/htFDnwWgi1

[JFPuget 🇫🇷🇺🇦🇨🇦🇬🇱 @JFPuget]

BTW, this is what happens in swe-bench verified.

Indeed, swe-bench test data is available as commits in github repos. Any frontier llm has seen these when training.

Numbers reported on swe-bench are not reliable.

[Subbarao Kambhampati (కంభంపాటి సుబ్బారావు) @rao2z]

While working on the CRC of our #ICML2026 position against anthropomorphization of LLM intermediate tokens, I can't stop chuckling re-reading my rebuttal to the reviewer who said that my sentences in the submitted version appear "overly AI-generated".. 😄

[pikuma.com @pikuma]

Nobody Cracks Open a Programming Book Anymore:

🔗https://t.co/JUyNkl1F8h

[Joe Weisenthal @TheStalwart]

I think we (as an industry) need to take really hard line on stuff like this. Fabricating quotes that get attributed to someone in a printed book imo egregiously bad behavior.

[Delip Rao e/σ @deliprao]

In-context learning in LLMs

[Arvind Narayanan @random_walker]

A big irony: The harder AI companies try to make their products feel like magic genies, the steeper the learning curve gets. "Prompt engineering" may no longer be a thing, but the verification challenge isn't going away — and it requires a *lot* of practice and learning to do well. Hiding the internals (reasoning traces, tool uses, intermediate outputs, memory, ...) makes it harder for users to build an accurate mental model of what is/isn't suitable to delegate, how AI handles complex tasks, what parts are most important to cross-check, etc. Even though hallucinations in a narrow sense are less frequent these days, reliability has become *more* of an issue because agentic AI has rapidly expanded the complexity and stakes of what people are using it for. The majority of workers are acutely aware of AI unreliability as well as other risks like skill erosion. So for the foreseeable future, a black-box user interface will remain a bad idea.

[Thomas Bloom @thomasfbloom]

Many people are not actually reading this.

Arxiv is -not- banning the use of AI, or papers which used AI to generate proofs, code, etc.

They are banning people who upload papers in which the AI content was (very clearly) not actually checked by the human author(s).

[Anna Riedl @AnnaLeptikon]

A classic.

[OpsConfig @OpsConfig]

@pikuma Thank you for unearthing this memory from my brain. I had to search for https://t.co/l2T6tR3GYQ to be sure. Immediately forwarded to my older brother for the shared nostalgia.

[Jeremy Howard @jeremyphoward]

The only correct answer when a VC asks: "What's your moat?"

[OpsConfig @OpsConfig]

@AlderLaneEggs Feels like a lot of people retweeted "Still, at the end of the day, this play for eBay makes perfect sense." And didn't bother to read to the end of his post published at 3 AM this morning before market open:

[Robin Hawkes @robhawkes]

This is my grandad, he built the original R2-D2 for the first Star Wars film…

Jack was a master sheet metal worker, and was roped into using his skills on an obscure project to turn the sketches for the droid into something that could be constructed out of aluminium sheets.

I always knew he'd helped make part of R2-D2. However I only found this photo in recent years and have since learned that he was actually instrumental to the construction of the entire droid, particularly with working out how to machine the complex shapes like the dome and legs out of single sheets of aluminium.

He didn't just build one either, he ended up constructing a handful of the droids for various uses in the film. I still have no idea how he did it, especially without modern software and computer-controlled machining.

Unfortunately I never got to know him as he died when I was a baby, though I have a feeling we share a lot in common.

I also have his old Dragon 32 computer that he was using to learn programming in the 1980s, with reams of hand-written code that still works on the computer.

#MayThe4th #maythefouthbewithyou #StarWars

[Daniel Litt @littmath]

Fully endorse this view. I have some worries about how AI tools will change the profession of mathematics, specifically around training. But the fundamental goal has to be to do good science, and clearly AI tools can help with that.