teaching

Jen, came in to see what incredible things the engineers and artists had come up with. Everyone was staring at a television set hooked up to a development box for the Sony Playstation. There, on the screen, against a single-color background, was a black triangle. "It's a black triangle", she said in an amused but sarcastic voice. One of the engine programmers tried to explain, but she shook her head and went back to her office.

https://neil.computer/notes/teaching-how-to-code-is-broken/

https://matklad.github.io/2022/10/19/why-linux-troubleshooting-advice-sucks.html

style

Composibility

Lets compare a few implementations of an INI parser. The best one has two functions; parse(string) INI and INI.stringify() string to convert ini data to and from a structured format. This is quite an elegant system which can be reused in many different instances.

Another way of creating an INI parser would be to have a parse(filename) INI function and a INI.write(filename) to save it back to a file. There's a few issues with this. First of all it makes the library useless for reading INI files which come from other sources, such as over a network, or even using a file reader that buffers the input for example. Second, this system often mixes filesystem reading error and parsing errors... if it even handles errors at all. Ultimately, it's adding complexity to something that would better be addressed by composing the library with some file reading function.

The third way would be where you must create an INI object, then load the file/string into your object, and finally use specialized methods to get at the results. This type of thing is common in the object-oriented tradition, and it's terrible. Instead of making a single function call and moving on, you now have to perform the ritual of moving your object through various states. And because data is now wrapped in a specialized object type, all code that interacts with it has to know it's type, creating unnecessary interdependencies. When a standard data type suffices prefer that over creating a custom data structure.

project documentation

Readmes, Changelogs, etc