cellio | Entries tagged with programming

I've been building and documenting application programming interfaces (APIs) for years, using tools like Javadoc to generate the reference documentation from the code and special comments in the code. I've got a pretty good handle on this in general -- but so far I've always worked in languages with stronger typing, like Java and C++, ones where the parameters and return values can be specific classes, or things like List<String> (rather than just a list), and so on. But now I need to do it for Javascript, where all the code will tell you is that that parameter is, say, an object -- not what specific properties that object needs to have and what their types are, for example. Our API is going to have a lot of that type of parameter. So now I'm wondering what's considered best practices for documenting those -- obviously the documentation from the comments has to address it, but I can imagine a few different ways of doing it and haven't found useful examples in the wild yet. (That doesn't mean they're not there, of course.)

I asked a question about this on Writers.StackExchange, hoping to tap the wisdom of the net. But I figure some of my readers might be able to offer suggestions. If you comment here you'll help me, but if you instead comment or answer there you'll help the broader internet. (Also, I'd like to see more technical-writing content there, for which there's a chicken-and-egg problem.) Either way, I'd welcome input, tips, warnings, horror stories... whatever you've got.

We haven't chosen a tool yet; we've found half a dozen for Javascript that we'll be looking at. So if I know what's considered the best way to do this I can factor that into the decision, instead of finding myself limited by what the tool we ended up with can support.

Today I attended a day-long class on web-service technologies. (Yeah, late to the party.) Being a programmer was not a prerequisite (though it helped), and most people there weren't. This wasn't so much about programming and software design as about getting from WSDLs (web-service specifications) to code and vice-versa, and about understanding all the pieces, the WS-* standards, etc.

I should also mention that at the beginning of the class the instructor asked us to introduce ourselves and say what we do. I mentioned API (programming interface) design, among other things.

One of the exercises was pretty straightforward: they gave us some Java code for a trivial web service, and we were to generate the WSDL from it and deploy the service. We were using Eclipse, which has built-in tools for this, so that's pretty straightforward. Some of my coworkers were asking questions about the Java code to better understand it (which is good, to be clear).

After this had been going on for a little while the instructor walked past me, saw me typing, and said something like "you're still working on this?". Well, not exactly on the assignment, I said; having finished that, I'd noticed a couple obvious omissions from the interface their service offered, so I was implementing them to make sure I understood how to wire it all up. He looked over my shoulder, said something like "that array might bring you pain; consider a Collection", I said I worried that that would be too Java-specific for a WSDL, and he pointed out that I was using a Java-specific tool and it would probably do something reasonable. And so it did.

After the class I apologized to him for being "that student" (I think I also asked more hard questions than everyone else put together), and he said no worries -- students like that keep him on his toes. :-) Me, I just wanted to make sure I got enough out of it to justify an 8AM start (ouch).

Part of this meme:

LISP

The most valuable part of my education as a technical writer was my student internship with the Common LISP project. It was also either the first- or second-most important part of my education as a software developer. Yes yes, the classroom stuff was important and the software-engineering project course was essential for putting the pieces together, but this was the real world and the real world is far less tidy than the classroom.

I was brought on to help write the documentation for this then-in-development language. (Other varieties of LISP existed; this was an attempt to unify them.) But unlike all previous tech-writing work, this was for a thing that did not fully exist yet, and I was part of the ongoing design process. I was there in the (virtual) room with the lead designers, Guy Steele, Dave Moon and dozens of others big and small, and if my contributions had merit it didn't matter that I was an undergraduate with no real experience. On the ARPAnet nobody knows you're a ~~dog~~ undergrad. Mind, being an undergraduate with no real experience, I didn't necessarily have a lot of design ideas to contribute, but even then I was pretty good at catching inconsistencies and asking key questions. I learned to write software-interface documentation there, but even more importantly I learned to be part of a real software-development process, to ask questions even if they might seem "stupid", to argue for technical positions and support those arguments, and to be a full member of a team.

When I graduated and met more of the real world I would learn that it usually doesn't work like this. In a lot of places, tech writers are not part of the development process (and may not even be in the development department) and the attitude is that they can come in after the big boys are done developing the product. Phooey on that; this important early experience taught me that it doesn't have to be that way, and I have held firm on this in every place I've ever worked. If I hadn't had this early lesson, I might well have fled the field.

It is also because of the Common LISP project that I went into programmer documentation (and expanded from there). I wouldn't have pursued tech-writing jobs that were all about walking the menus in the UI and stepping through wizards and such; I want to look under the hood, understand what's there, and use that knowledge to help users. Building software development kits like I do now is exciting and nourishes my inner geek. When I went to college I hadn't even heard of technical writing (I went there to do computer science), but I came out as a technically-proficient writer who knows the good that is possible. I have Common LISP to thank for that.

Since about 30 seconds after LJ announced the tagging feature I have been wanting boolean search for tags, so that I could find entries tagged A and (B or C) or the like. This has never been possible.

Today in

news they announced that you can search for entries with two tags (specifically two) using the following syntax:

http://username.livejournal.com/tag/tag1,tag2?mode=and

(Substitute for username, tag1, and tag2, of course.)

That's great. This will help. But I can't help wondering... why this implementation? I tried it with three tags; it took the first two and ignored the third. I tried mode=or; didn't work. I assume from this interface that they'll be extending this to support the latter; it makes sense to introduce a "mode" argument now and support other options later. But what kind of implementation limits the parameters to two? I'm trying to imagine the design that produced this result and seemed like a good idea to the dev team, and I'm coming up blank. (Yes, I know LJ is open-source so theoretically I could go look. I don't care that much.) Isn't it just as easy to process arg1,arg2,...argn as to parse arg1,arg2?

So yay for the beginnings of expressive tagging, but I do hope more is coming.

Pesach has been going well. Tonight/tomorrow is the last day, which is a holiday like the first day was. Yesterday Rabbi Symons led a beit midrash on the "pour out your wrath" part of the haggadah; more about that later, but it led me to a new-to-me haggadah that so far I'm liking a lot. (I borrowed a copy after the beit midrash.) When I lead my own seder (two years from mow, I'm guessing?) the odds are good that it will be with this one.

Tangentially-related: a short discussion of overly-pediatric seders.

Same season, different religion: researchers have found that portion sizes in depictions of the last supper have been rising for a millennium, though I note the absence of an art historian on the research team.

Same season, no religion: I won't repeat most of the links that were circulating on April 1, but I haven't seen these new Java annotations around much. Probably only amusing to programmers, but very amusing to this one.

Not an April-fool's prank: xiphias is planning a response to the Tea Party rally on Boston Common on April 14: he's holding a tea party. You know, with fine china and actual tea and people wearing their Sunday (well, Wednesday) best. It sounds like fun.

Edit (almost forgot!): things I learned from British folk songs.

From nancylebov: Harry Potter and the Methods of Rationality looks like it'll be a good read. Or, as siderea put it, Richard Feynman goes to Hogwarts.

Real Live Preacher's account of a Quaker meeting.

Thanks to jducoeur for a pointer to this meta community over on Dreamwidth.

I remember reading a blog post somewhere about someone who rigged up a camera to find out what his cat did all day. Now someone is selling that. Tempting!

In case you're being too productive, let me help with this cute flash game (link from Dani).

Dani pointed me to Fantasy In Miniature. here are three that caught my fancy. I have just doubled the subscriptions to

fantasyinmin. (I wonder who the other one is.)

From

siderea: The C Programming Language by Kernighan & Ritchie & Lovecraft.

Toleration versus diversity (David Friedman) was an interesting read for me.

Chat-based ask-the-rabbi service, for when email is too slow and asynchronous. Apparently they also do SMS. (It's Chabad, though they don't make it particularly easy to discover that.)

Usually mail addressed to "resident" is a write-off, but yesterday we got a letter in a small envelope with a handwritten address to "current resident", which is unusual. Inside was a postcard/photo of our house from circa 1930. The accompanying letter explained that the writer had found it in a scrapbook and since it actually had an address written on the back, she wanted to send it to us, whomever we were, assuming the house was still standing. Neat! So we're going to send back a current picture, along with one of its near-twin two houses up. (Ours and the other house are mirror images of each other.)

The South Side, where I work, has been devoid of Indian food -- until now. Sree's, of CMU lunch-cart fame, has set up a satellite in a kiosk at the end of our block. Yay! An actual restaurant would be better, but I'll take "surprise vegetarian combo of the day" in steamer trays if necessary. It's still pretty good. Qdoba, let's just be friends, ok? :-) (I actually bring my lunch almost all the time, eating out maybe once every couple weeks, but when I do go out it's usually for the pseudo-Mexican salad.)

Quote of the day: "See, in Java, they force you to hack your way through the jungle with a machete. In perl they give you a flamethrower, and afterward you root around in the ashes for the data you wanted. The styles are somewhat different." -

dvarin, here.

You can get almost anything at Amazon (link from

merle_). Be sure to read the reviews.

The digitize-our-albums-and-tapes-before-they-rot project is still mainly in analysis mode (figuring out where to acquire what), though we're grabbing the low-hanging fruit as we see it. This will take some time. Meanwhile, we learned tonight that while you can nominally share your iTunes library with other machines on the local network, you can't actually do much with that -- you can't add non-local files to playlists or iPods, which sort of defeats the purpose, no? (And iTunes has to be running on both machines to even listen.) Just copying the files from one iTunes directory to another doesn't seem to do the trick, either. Sigh. Are we really going to have to import everything CD by CD and track by track (for the downloads) in order to share everything?

The bookshop that has all the books in the world -- except one is a lovely 8-page graphic short story (link from

shewhomust).

Joel on Software and Coding Horror (I hadn't heard of the latter before but looks interesting) have launched Stack Overflow, which looks like it could be a good resource for answering technical questions. (I hope that by logging in with my LJ OpenID from home and saying "always accept", I'll be able to answer questions with that ID from work where LJ is blocked.)

Programmers as carpenters (short).

Harold Feld's analysis of the Palin camp's attack on Oprah (part one). This story fizzled soon after hitting CNN on Monday; I hope that's the last we hear of it, but it seems plausible that it could come back on a slower news day. Sheesh. Usually it's folks from the left who assert that freedom of the press means you're entitled to someone else's press.

A few on the economy, some serious and some light (because sometimes you have to laugh to avoid crying too hard):

We've all seen that ABC graph comparing the Obama and McCain tax plans (sorted by bracket). Here's a version that's closer to scale (link from anastasiav).
Scott Adams surveyed economists to try to find out what the experts think about the candidates. A surprising (to me) number said it doesn't matter which candidate wins (on this set of issues).
An article on the current troubles by one of the Nobel laureates in economics. Interesting on first reading; I haven't dug deeper yet. And, as demonstrated most recently in the previous bullet, economists don't tend to agree on much.
This picture turned out to be sadly ironic.
Didn't anyone consider this angle on the looming economic disaster? (Onion video from rjlippincott).

I guess I shouldn't be surprised by bit rot. I've been at my current employer for several years, and our code base is Java (and now a little bit of C#). Today we interviewed a candidate whose background is primarily C with some C++. I was about to write the programming problem on the whiteboard, translated from Java to a language he'd be more comfortable in... and had forgotten too much syntax. Oops! I used to be proficient in both. I still know C++ well enough to work in (on existing code), and of course can still speak to it on a conceptual level, but I no longer know it well enough to generate from scratch. Bummer. I guess when you install Java you get garbage collection. :-)

(Just checked; still have rudimentary LISP. Good.)

Speaking of bit rot, from the "yes we really talk like this" department:

While discussing the too-old bread that was being disposed of:

Dani: Bread makes its greatest contribution to the ecology in the third week.

Me: No, bread makes its greatest contribution to medicine in the third week. It makes its contribution to ecology in the sixth week.

(In my defense, he bought the bread while I was out of town and it sat there neglected all this time.)

Speaking of food, yesterday was the last day at work for one of our more technical technical writers (not in my group), one of the primary implementors of our current XML-based system (DocBook-based). Another coworker got a cake, inscribed as follows: <colophon><para>We'll miss you Bill</para></colophon>. She did it herself; I can only imagine the things that could have gone wrong if phoning that in to the bakery. It went over well.

Quote of the day: "Don't worry if you don't know what eschatology is; it's not the end of the world." (From Dani.)

This map shows the dominant words used for soft drinks across the country. I don't know what's going on in Alaska, or in that swirl of yellow over Missouri.

Word of the day: insinuendo. (Applied to the phrase "sometimes it works the first time", referring to software development.)

Seen in a book on design patterns: "If it walks like a duck and quacks like a duck, it might be a turkey wrapped in a duck adapter".

This one's been around for a few days, but in case there are folks who haven't seen it: a fun way to deal with folks who are stealing your wireless access (though tsk tsk for not locking it down if you care).

I had not heard of the meme of fabricating large-scale implementations of food until a coworker posted his version of Hostess cupcakes.

nancylebov posted two anecdotes about music gone wrong. The first is probably true and the second probably isn't, but I found both to be very funny. And as for the first, well, it couldn't happen to a better genre. :-)

Dani sent me a link to a bad citizen in Java-land. Yeah, don't program like that. :-)

In context this made perfect sense. Out of context, I'm glad no managers were walking by at the time.

"Well, if you don't want to do incest, nepotism will work."

(A coworker needed to cons up a relationship diagram with doubly-linked nodes, like a spouse who's also a sibling or a child who's also an employee...)

Good news: the folks at Sun are considering adding an @exclude tag to the standard doclet. The tag could be used at the class or member level to prevent production of javadoc for that item. I need this feature; in fact, we wrote a custom doclet to get it, but every new release of Java has forced a new layer of kludges onto that doclet and it's now quite unmaintainable.

Bad news: this feature has been pending since 1997.

Hot. Hot hot hot hot hot. And muggy. And did I mention hot? I really hope the AC guys we're talking with next week can do something for us. Their pitch is, essentially, "if you've been told your house can't accommodate central AC, talk to us". Yup, that's our situation. And window units can only do so much.

I might see psu_jedi and caryabend tomorrow morning. Woot! They will, alas, be spending most of the weekend with the relatives they actually came here to visit, but with luck we should get to see each other briefly. It was so nice to finally meet them at estherchaya's and sethcohen's over Purim!

Sunday night is Shavuot. I'm looking forward to the late-night torah study. The evening service, which is confirmation, I can take or leave; I'll go if it and dinner plans don't bump into each other. And I will, of course, be there for services in the morning.

My week was full of demands on my time that aren't part of the project plan. The project manager will not be happy when we next meet. Some of it was important stuff that needs to be done; some of it was extra administrivia caused by the corporate buy-out. I've now spent about 6 hours on the VPN problem and it still doesn't work, for instance. Whee.

But I did accomplish one useful thing today: we've been asking for a little developer time for months to hook online help into our product, but the project and product managers keep saying that while this is important, other things are more important and they can't spare anybody, even for half a day. So I finally just did it -- forgiveness versus permission and all that. As soon as I have a real doc set to launch instead of Shakespeare's sonnets, I can check it in. The project manager was going to be a little grumpy anyway because of things beyond my control this week, so I may as well get something I wanted out of the deal. Waste not, want not.

This exercise did make me just a bit more aware that I would benefit from a structured learning experience on the subject of Java. I've been picking the API up by osmosis, and of course I already know general programming principles, but when I have to do something completely new I usually end up asking a coworker for a pointer. That's not good; I should be able to do more of this on my own. (Today it was resource access through ClassLoader.) I wonder if I should just take a course from Sun or something. If I do, I wonder if there's any benefit to then taking the certification exam.

Obligatory Frienditto thingy: I'm not using it (really see no point; my journal is archived on LJ and on my computer). I expect that no one on my friends' list would violate my trust by publicly posting locked entries. I presume the tempest in the teapot will die down Real Soon Now.

Shabbat was pleasant. Saturday morning a young man who was bar mitzvah last summer read torah for our minyan (for the second time since his bar mitzvah). I'm glad that he's continuing to both attend and participate, and that he feels comfortable reading in front of our group.

The start-up that Dani works for has a major deadline Monday, so he worked all day Saturday. And all evening, and night. Whee. I met him for dinner after Shabbat and then met his co-workers. When we walked in the lead engineer turned to me and said something like "ready to write some LISP?". I said "LISP? I thought you were a Java shop", and he shrugged and started talking about something else. So I gave it no further thought at the time, figuring it was some sort of odd joke or something. (I just assumed that Dani had, somewhere along the line, talked about his wife the former LISPer.)

I asked Dani about it today, and he said that, in fact, one third-party tool they have to intergrate with has an API that resembles a cross between C and LISP. I didn't ask for details, but he said there's clearly a LISP interpreter under there somewhere because they get error messages that include names of LISP functions. Weird.

It's been almost 15 years since I wrote LISP professionally, but it was a fantastic language and if I'd known the guy was serious, I would have asked him to tell me more. I'd have been willing to give them a couple hours. (I have another friend there too.) Now, it probably wouldn't have been a net savings for him, because he would have had to teach me enough about the application to be useful, but...

I just wrote an ant target to call a bat file to loop over all files of a given type and call a different bat file. (This last bat file doesn't understand wildcards, and it's commercial software so I'm loathe to hack at it.)

I feel dirty.

(I couldn't figure out how to write the loop within the body of the ant target, which would clearly be better.)

gregbo asked a question in a comment that I decided to bump up to the top level:

You've written a lot about how you don't think you'd excel at programming if you went back to it ... why do you feel that way? What do you think is the difference between someone who excels at programming and someone who doesn't? Is it a "time spent" issue ... could you make yourself better at programming if you spent more time on it? Would that perhaps make you unhappy, because you couldn't spend more time doing other things you enjoyed more?

( Read more... )

A few days ago Joel Splosky posted an article about why (some) software methodologies are bad in which he said that he has trouble explaining a certain concept that comes across more clearly with Hebrew terminology. Being both a technical writer and sufficiently proficient to understand the (simple) terms he was using, I decided to take a crack at it.

His followup, based on a response from an Israeli, was much better than mine (also different in some ways), which is presumably why he chose to publish it. But he complimented mine, which suggests to me that I didn't completely miss the mark.

( read his original article first or this won't make sense )

Attention appliance manufacturers: there are correct and incorrect ways to fail. Correct is to unambiguously modify output upon failure, so the user knows there's a problem. Incorrect is to blithely go along reporting bogus information while your sensors fail, such as an oven reporting the wrong temperature, a radar detector failing to see the bogeys and reporting that all's clear, or a bathroom scale reporting the wrong weight. Maybe the last isn't as important as the others, but it's still annoying. Stop that. I didn't gain 10+ pounds by changing a battery; honest. You could have beeped or flashed at me to say "battery is low", you know. Sheesh.

An SCA officer posted a badly-worded announcement to the kingdom mailing list, prompting the vast quantities of speculation and challenges that she had hoped to avoid. (There had been none previously on this list.) There are better and worse ways to announce that something bad happened but you're not allowed to release any information yet. A good one is to say, e.g., "It is my sad duty to report that an SCA participant died at a fighting practice this weekend. We do not yet have permission from the family to release more details. Stay tuned.". A bad way is to say "something bad happened, please don't spread rumors, you'll be told what you need to know later, the presence of the word 'sad' in the subject line should give you a hint (nudge nudge, wink wink), no we really won't tell you anything, don't worry about it, don't bug us, and don't gossip". That trick never works. (As the moderator of a related mailing list, I now get to decide how much of the resulting traffic should get through.)

I would like for Java to provide one more publicity level than it does: "internal-public" (or, conversely, "api"). Not all public classes are meant to be used by applications; some are public only because they have to be visible to other classes in your code base. I'd like to be able to label which are which. I'm using a customized javadoc tool to produce the subset of documentation we want, but I get no compiler support this way, so I have to rely on home-grown tools and visual inspection to determine whether I have a self-consistent subset tagged for the API. This could have been easier, given perfect foresight. I'd be delighted if it were easier in the future. (I understand that .NET has a similar concept.)

( 5 good questions )

The Rules:

Leave a comment, saying you want to be interviewed.
I will respond; I'll ask you five questions.
You'll update your journal with my five questions and your five answers.
You'll include this explanation.
You'll ask other people five questions when they want to be interviewed.

One of these years I may make a real effort to compile some of what I do into the beginnings of "Tech-Writing Pearls", but for now all I'm doing is stashing stuff away when I realize I've written something that could be fodder later. Like now. :-)

On an API-documentation list someone asked about verb choice for access methods -- "returns", "gets", "retrieves", "queries", and so on.

I strive to be very careful to expose the correct amount of implementation in the documentation. That is, sometimes we only want to promise that we return a value somehow. Other times, we want to convey to the user that a new computation (e.g. a database query) is happening, which should affect the conditions under which he calls the method. So, using a word that implies computation when we're promising not to compute actually makes things worse.

I use "returns" almost universally. If we're actually computing or fetching a value, and this behavior is part of the interface specification, I'll say that, but I'll also try to get the programmers to name the method something other than "getFoo" in that case, too.

I view the method itself as the subject of the sentence, so I dislike "gets" because that's not what the method does. Your code is getting a value by calling the method, but the method does not "get", it "returns" or "provides access to". This may seem like excessive anal-retentiveness, but there can be cases elsewhere in an interface where it is not at all clear where the work gets done, and I find that if I am stubbornly consistent about using verbs that apply to the method (rather than the caller), I can reduce the potential for confusion elsewhere. My readers can learn the pattern if there is a pattern.

Update: I intended to focus here on what to say in the documentation, and not how to design the API, but I probably didn't make that clear enough before. Sorry 'bout that.

Java compilations are much, much faster than C++ ones were. I must remember this when I get impatient.

One lane of the Boulevard of the Allies has been closed for a couple weeks due to construction. It's only closed for a block, and generally it doesn't hinder traffic flow. Today, however, traffic was crawling there, and I have no idea why. What, did last night's spectacular storm cause drivers to be afraid of puddles or something? Sheesh.

The storm was quite loud and bright last night. I think I jolted awake from proximate thunderclaps at least three times. This made the cats who were sleeping on/near me unhappy, but it wasn't exactly under my control. This morning it seemed to have cooled things down and sucked some of the humidity out of the air, though the effect apparently didn't last. (I haven't been out since morning.)

Sharon and Elliott have a new cat. It's shaped like a Siamese, but it's all white. Elliott told me that because it has green eyes it is an "Oriental Shorthair"; if, instead, it had blue eyes, it would be an "Unpointed Siamese". Eye color is a defining characteristic of the breed but pointing is not? I didn't know that.

I am, I am told, abnormally good at naming classes, interfaces, methods, and the like. Other developers routinely come to me for help with naming things they're developing.

Today a developer came to me with a slightly different request. He has decided he's not good at naming, and he thinks he's not the only one, and would I be willing to give a little seminar or something on the how-tos of good naming? (I've already written a document, but it's practical advice and dos/don'ts rather than methodology.)

I'd like to do this. If successful it would improve the code base and give me a little visibility boost. Now I just have to figure out how to tease out the science (methodology) from the art (instinct); I'm guessing the former is teachable in this format and the latter isn't. The art (of anything -- programming, crafts, others) is why internships and apprenticeships exist -- you can't just do a brain dump and go.

Drivers of school buses should set better examples. A couple days ago I watched a school bus be the third vehicle in a line of traffic that was running a red light. Sheesh. (In case you're wondering, no I was not at the head of that line. I was at the head of the line of traffic that had a green light but couldn't safely move.)

Last night was Temple Sinai's annual meeting. Doing back-to-back meetings for two different congregations led to exercises in comparative anthropology. Tree didn't really give a "state of the congregation" talk; Sinai did but they painted a picture that's a tad more optimistic than the facts really support. (Nothing untoward, mind -- just PR spin.) I wonder which is worse -- no info or sanitized info.

This Shabbat it's my turn to bake for the kiddush. I wimped out; you can get these "instant cookies" that you just break apart and stick on ungreased cookie sheets. I'm not usually that much of a slug.

Much to my annoyance, I learned today that the java compiler isn't as smart as I thought it was. Suppose your class has a method that returns an instance of your class. Suppose you subclass that and want to override this method to return an instance of the subclass. If Base.fn() returns a Base and Derived.fn() returns a Derived, you would think that the compiler would be able to tell, given code such as "Derived d = Derived.fn()", that it should use the overload that returns a Derived and not try to return a Base, right? You'd think so, and I'm told the spec says so (though I haven't checked), but apparently you'd be wrong. Bah.

We watched the season finale for "West Wing" tonight. Some interesting developments, some disappointments. The end of the CJ story was particularly annoying to me. But overall, I'm enjoying this show. We've only been watching it for a couple months. (We encountered it for the first time over Pesach.) I haven't gotten around to the season finale of "Enterprise" yet.

Dani is talking semi-seriously about buying the first season of "West Wing" on DVD. This must mean he's thinknig about getting a DVD player -- which must mean that he's inclined toward that TV upgrade. The (new) TV room is currently under some construction, but that should be done soon. Then we can do furniture.

Our D&D party (in Ralph's game) has some down time between now and the next session. Real Soon Now I need to figure out how my character is spending it. I'm really enjoying being in a D&D campaign again; it had been a long, long time (12 years or so). I like to think that I'm a better player now than I was then, just due to general maturity, though I don't actually know that.

I'm feeling better. I still don't know if it was food poisoning or actual illness, but whatever it was, to my relief, is gone.

I missed a code review yesterday because of the crud, so today I went over my comments with the author. He said I obviously read the code more thoroughly than any of the people who were actually there. I think it was a compliment. :-) I've been invited to another code review (different author) tomorrow; the current code marshall likes it when I participate in code reviews, it would appear. (The code marshall decides what will be reviewed and by whom; the position changes monthly. Usually we have one code review per week, sometimes two.)

I wrote actual code against our API this week, starting from first principles instead of starting from other people's applications (or test code). It's nothing especially fancy or clever, but it's just what it needs to be: a simple, basic example on which to build more-involved examples, in an organized fashion, for our customers. This series of apps, which I'm doing with a senior developer (he's going to end up doing most of the coding work, but we're participating equally in specification and design) will form the basis of some tutorials that I will write. The whole experience makes me happy, even if I spent way too long banging my head against the wall Tuesday over what turned out to be a stupid mistake on my part. Still, if I don't get it the customers never will, so better that I bang my head against these things than hand-wave around it and assume I could write apps against the API....

Monica

documenting APIs for weakly-typed languages?

there's one in every class

how LISP changed my professional life

LJ tagging: baby steps

short takes (link round-up, mostly)

a few links to share

random bits

harvesting some browser tabs

random bits

short takes

a few links

this could be taken the wrong way

javadoc: good news, bad news

random bits

miscellany: frienditto, Shabbat, programming

embarrassing code

programming

Joel on davka

grumpy (but light) short takes

interviewed by tangerinpenguin

tech-writing geeking

short takes during a long build

can I bottle that?

highly random

progress

Expand Cut Tags

Syndicate