It seems like almost everyone has written an SMTP server; I use https://github.com/tijn/devmail which has no web interface but a POP server. This is by design so you can see your mail in an actual mail client like Apple's Mail.app or Thunderbird.
So, we now have tldr, and navi, and mnemonic, and cheat, and maybe some more similar tools. But why don't we add these examples to the respective man pages? There's clearly a need for them.
I guess if you wanted you could make a new command that only prints the EXAMPLES section of a man page. It could turn out to be an improvement even since you get all the nice things that man provides like colours and consistent formatting for free.
Last summer I took a detour to visit the exposition in Helsingborg. I remember seeing New Coke and the Newton. I think I saw MS Bob too, I could be mistaken though.
By the way, I think the collection has potential to grow a lot bigger and I would have liked to seem more in-depth information about each failure. Maybe the hacker-news community can help with that. (Surely someone here must be knowledgeable about failure :-P)
I once accidentally took a tour over the top floor. I read warning signs on the wall that told me to keep all limbs and especially hands in the cabin. Then it became rather dark since there was no light bulb in the cabin. After a short while, when my eyes got adjusted to the darkness and a bit further up I could see why the warnings were there: I could see the whole mechanism that drags the chain of cabins around. Big cogwheels only centimeters away from the door. I kept my distance from the door opening and I arrived at the top floor again where I got off.
Thanks to the warning signs I wasn't really afraid. They made me realize that this sort of thing likely happens quite regularly.
I recently ported a small combined SMTP/POP3-server (from Ruby to Crystal) so I can read the mail from my projects in Thunderbird or the OS X Mail app. Yes, this is another shameless plug, but I hope it's useful: https://github.com/tijn/devmail
Yes, that is almost exactly how I would rewrite it. The original doesn't communicate its intent at all. It makes one itching to rewrite it but, it takes some time to take all the "smartness" into account.
The original line raises surprisingly many questions:
- The default for `split` is to split on whitespace. Is it the intent of the author to only split on spaces? (I guess so) What about tabs?
- Why is the author using #map! (with exclamation mark)? I have to admit this put me on the wrong foot for a while. My best guess right now is that the reason is speed; Mutating the array that split produced is (slightly) faster than creating a new one.
- Why is the capitalized string assigned to x again? I can think of no good reason at all. Am I missing something?
- Why is the author using x[0..0] instead of x[0] or x.first? I know why: The difference is that the latter two return nil if x is the empty string; but it's far from obvious and one could easily break the code by trying to improve this.
- Why are the parts of x concatenated with << instead of with +? For speed? Is the author not aware of String#capitalize ?
One-liners are fine if you know you'll never need to extend the logic later on. Problem is, how often does that stay true?
For instance your 'titleize' method, in order to properly title case any string, ought to support a second option of words to ignore, such as "a, an, the, ...". If you wrote it as a one-liner at first, then you've got to go into your mapper and add conditionals if an ignore list is passed, and you've got more work than if you left it as a more expanded piece of logic.
Again, this is somewhat of a trivial example, but building on the original post's point of "how easily can I understand this later on" can also include "how easily can I extend this later on". Avoiding one-liner cleverness can help as a general principle.
