getluky.net

Because i’m a lazy programmer, I like things that save me time. I don’t like having to keep phpdocumentor/doxygen style code up to date with the actual code inside a function. Also, including a documentation compilation step in a build process is annoying, and phpdocumentor/doxygen don’t result in a clean data source of functionality metadata that I can produce my own documentation interfaces from.

So, I guess you could say that there are two main problems I see with a phpdocumentor/doxygen style approach. First, it’s duplication of information. Aside from the DRY (Don’t Repeat Yourself) principle, this is a step worse because you end up repeating the information at least twice, both in code and also in some separate documentation format. That’s annoying, and it will be easily skipped by programmers in search of quick fixes. Secondly, there’s no live source of trustworthy metadata data where one can get at it easily in a programmatic way, without a compilation step.

A good solution presents both a structured data source of documentation, and also avoids needless repetition of information between the code and the docs.

So, since documentation about functions and their parameters is simply metadata about the function, why not store the documentation in data structures within the function itself?

The way I started solving this problem by taking a page from a subset of a hardcore approach to programming called Design by Contract. I’d heard about it before just as a general concept while doing my time in an undergrad CECS program, but always figured that it was too serious to get into. It was really fun to recall this old foggy concept while I was deriving a pretty useful solution to the problem described above.

The entire goal is to convert function docs from these specialized comment markup formats into a machine-readable data structure inside of each function. One will need to define a standard data structure in which to store metadata about a function’s parameters. This will vary depending on the programming language’s embedded types and parameter semantics.

Once a structure is defined, then one can standardize a method of passing in a documentation request struct reference to each method, and when the method notices it, it can simply fill it with the doc metadata and skip the normal control flow for the function. It’s essentially the same as asking a function to describe itself.

Secondly, one can immediately go about enhancing the parameter data structure to include detailed information about each parameter’s type, expected inputs, etc. This information can doubly be taken advantage of by writing generalized validation routines that use this metadata about parameters. If you were going to write validation routines anyway, this saves you having to needlessly repeat that metadata within code.

Thirdly, one now not only has quick, programmatic (and realtime, not compiled) access to function definition metadata, but it’s also more or less in exact sync with the actual parameters it expects, and it also in a standardized data structure. So one can dynamically generate an entire interface for say, spelunking through an API, out of the simple presence of functions that know how to document themselves.

You do pay the price of some realtime overhead, but the very real benefits in maintainability and elegance far outweight that, in my opinion. The implementation of this general derivative concept is pretty academic if you understand all the nerdery above. The key thing to do is to just take a page from Design by Contract, and have your program know about itself, rather than hiding its metadata within invisible comments.

By far, KSCU, Santa Clara’s college radio station, is the best radio station in the Silicon Valley. It’s more or less on permadial in my car, and because of it I haven’t had to go searching for interesting variety in music. Having college age kids with diverse tastes playing and saying whatever they want makes for very few boring shows.

My favorite one is Beer Run Bobby’s 408 Oldies Show. Track after track of oldies songs that i’ve never heard before, interrupted by shouts of “KSCU! MAKIN ALL THE CHOLAS HORNY!” I’ve probably heard very few radio shows as compelling, fresh, or original as this one, and i’m talking about the greats like Joe Frank and Garth Trinidad’s shows back in the KCRW of old. Anyway, i’m listening to it right now, and I love that shit. Give it a listen Sunday nights or anytime live 103.3 in the Yay, or via their streaming internet radio.

Feature f*cking: when you work nights and weekends to get a release or product shipped, and then the first thing that some people do is deliver a negative and disheartening soliloquy about what features it lacks.

Usage in real life:

You: “I just released this new thing! Check it out!”

Them: “You know, this would be good if only it had these billion features.”, or “I can’t believe you didn’t do X, are you stupid!?”

You: “Dude, you’re totally feature f*cking my product right now.“

Please just take this at face value, as a way of a defusing a negative situation with some good old fashioned vulgarity.

However, if you really want to know the full (mostly depressing) meaning behind the phrase, read on.

The choice to launch a product signifies an inflection point where the software works and fulfills an key need far more often than it breaks, and the fundamental use cases have been addressed. Chances are, the vision for the product is already far out there and the billion features suggested may already be in mind, but the reality of shipping code forces practical constraints on everything. It’s a compromise like that of politics, the “art of the possible.”

Of course, I understand people feel the need to deliver litanies of features.

Sometimes, it’s a genuine need that hasn’t been addressed (like internationalization). In most of those cases, the features will be addressed when possible and the developers have energy, but not before. However, ranting and raving about how idiotic a developer is because they haven’t internationalized yet is NOT the proper way to go about encouraging a developer to do so.

Other times, for the tech elite, there is too much software released to actually use it at all. It’s much easier for them to “see the big picture,” where every new product is just a puzzle piece joining in assembly of a vast futurist perspective. Keeping abreast of every startup that appears is surely overwhelming for anyone, and I can understand that to some, the only way to cope is to treat the creations of techies as assemblies of features that are always disappointingly short of science fiction.

The hidden story here is that of developer happiness. No matter how many community managers are out there trying to politely thank people for negative feedback, there are always human beings behind them writing code and deciding which features they are excited to work on or not. Certainly it is true that professionalism is somewhat about doing what you need to do despite whether you want to do it. However, the attention to detail and love of a product is difficult to cultivate in a negative atmosphere. Hearing about all the features you’re lacking or missed is one pretty negative way to influence a developer’s opinion of work that they probably had to do anyway.

Jefe: We have many beautiful profiles for your birthday celebration, each one filled with little surprises!

El Guapo: How many profiles?

Jefe: Many profiles, many!

El Guapo: Jefe, would you say I have a social network of pinatas?

Jefe: A what?

El Guapo: A social network.

Jefe: Oh yes, El Guapo. You have a social network.

El Guapo: Jefe, what is a social network?

Jefe: Why, El Guapo?

El Guapo: Well, you just told me that I had a social network, and I would just like to know if you know what it means to have a social network. I would not like to think that someone would tell someone else he has a social network, and then find out that that person has no idea what it means to have a social network.

Jefe: El Guapo, I know that I, Jefe, do not have your superior intellect and education, but could it be that once again, you are angry at something else, and are looking to take it out on me?

One of the things i’ve done without any modicum of regret is the switch to buying only all-natural peanut butter. It tastes like a completely different spread, much richer in pure peanut flavor, and missing all of that orangy preservative aftertaste. Not only that, but the first few spreads from the jar are gloriously creamy and delicious.

However, many people get turned off by the oil at the top of the jar. That’s why i’m writing this post - after a few years of eating this stuff for occasional PB&J’s, i’ve got a few tips to share that are more or less obvious in hindsight.

First off, to get a good initial spread, it’s really important to thoroughly mix the peanut butter paste with the oil. I usually jab downwards with a knife to the bottom of the jar, which allows the oil to seep down into the paste. After doing that for a while, it lowers the oil level somewhat so that you can move on to jabbing downwards then pushing around the jar. Since the paste is normally pretty hard, it’s easier to do this once the oil loosens up the spread a bit. After that, it’s a simple matter of stirring.

This will give you a great jar of peanut butter, until you get to about the halfway point. You’ll notice that the oil tended to float to the top, and now you’re left with a half jar of very stiff peanut butter. The second tip is just to go out and get some run-of-the-mill peanut oil, and add it into the jar, repeating the stirring process again.

The last problem that I sometimes deal with is that i’ve sometimes got a soft bread and cold PB, which can easily tear the bread when I try to spread it evenly. This becomes an issue when you refrigerate your PB after opening, especially when getting towards the bottom of your jar. Although some oil would help, if you’re feeling lazy, here’s an easy trick. You can take your butter knife and pre-spread the PB on the sides of the jar. Just take the big clumps of PB and smooth them out along the sides of the jar as if it were a really stiff bread. The more you work with it, the more pliable it becomes.

So anyway, I hope that if you’ve been previously dissuaded from using natural peanut butter because of the oil or the stiffness, you’ll come back to it and give it another try. That’s all for this food-related post.

There he is! Get him!

(Context)

The easy and fun way to test whether a mission statement/purpose/motto is garbage is to negate it and see whether it still holds up. If a mission statement does not make sense for a company not to do, then why even bother stating the obvious?

Striving to be a leader in a field? Of course you are - you better not be trying to come in dead last…

Trying to connect people to passions or interests? Hell, why not disconnect them instead!

Don’t be evil? Have you tried being evil? Was it so bad?

Just do it? Have you considered the consequences?

To me, mission statements sound as disingenuous to me as the parenthetical phrase “to be honest.” The best possible response to a sentence that includes that phrase is “Please lie to me instead.”

Douglas Adams wrote frequently about the human penchant for continuously stating the very, very obvious. Mission statements take that principle to the extreme, to the point where we even believe that we’re going to persuade people about something or other by making an official public statement about what we are going to do that would be insane to negate.

In fact, I can’t think of a single catch-phrase that motivated individuals through an extended period of time, except for perhaps “Go forth and multiply,” but one could easily see that the instruction wasn’t really necessary, just the equipment and instinct.