cellio | Entries tagged with programming

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....

I am an under-educated wimp not worthy to even think about this, but some of my studly friends might find this interesting:

http://www.topcoder.com/

Aha. It *is*, theoretically, a simple matter of programming.

A while ago, I described an API-validation problem. One of the tools I have available is the generated Javadoc for the candidate API. And Javadoc, as it turns out, does something reasonable if a method signature references a package it can't find: it simply spells out the name of the package, rather than providing its usual link. So, for example, if Foo is in the API and Bar is not, you'd get something like this:

public void doSomething(Foo, com.mayaviz.something.Bar)

where the underlining is really a link to the Javadoc for Foo.

Ok, fine and dandy; I have the beginnings of a grep-based solution. I can grep all the Javadoc looking for "com.mayaviz" -- but it's not that simple, because the legitimate links (like Foo) will have that in their URLs. So I can either post-process the grep output to throw out links, or avoid generating that output in the first place.

So what I *really* need is a very specialized parser: eat stuff until you find a <pre>, then until </pre> do this: eat everything in an <a>...</a>, and other than that if you find "com.mayaviz" spit out a report. Iterate until done.

Now I need to learn enough Perl to actually write the sucker... (I am not a Perl hacker. Not by a long shot.)

Maybe the process of writing this down will help me clarify the problem in my head.

We have a mucking huge API for our Java toolkit. (Well, incipient toolkit.) My goal is to make a smaller API. There's a lot of stuff that's currently public that doesn't need to be and cutting that out is easy. The hard part is making sure that the new, smaller API does not refer to classes or interfaces that are no longer public. (By "refer to", I mean appearances in signatures. For example, if the constructor of PublicThingy requires that you pass a NoLongerPublicThingy, we're in trouble.)

There has *got* to be a programmatic solution to this problem -- either out there already or feasible to write. What I want to be able to do is specify an API, crank it through some process, and get back either "ok" or "oops, still have refs to the following: ...".

This is an API, not an actual smaller code base, so it's not as simple as removing files and running the Java compiler. Everything will still be there; it's a question of what we expose.

The specification of the API is the javadoc. I of course have access to the source code, but I don't think crawling through that is the way to go.

Some args to methods will be objects in our API; others will be Java classes (JDK) or base types (like int). So I can't just compare signatures to our list of classes; I need a way to weed out the standard Java stuff. So I need to be able to tell the difference between NoLongerPublicThingy and Double.

One way to attack the problem would be to generate the lists of permissible objects and then run all the signatures through something that compares to that list. Ugly and slow, but I suppose it would work. Feels like a gross hack, though. (Javadoc generates the lists as part of its normal processing, so I can just grab the list from the JDK Javadoc.)

A more elegant solution would involve modifying Javadoc processing itself to do this checking as it goes. After all, it's already doing some processing on each signature to do its formatting and links and stuff, so why rewrite the code that parses signatures? On the other hand, I don't know how feasible it is to modify Javadoc. (Yeah, it's *possible*, but I don't know anyone who has actually *done* it.)

Another approach is to treat this as a general interface-validation problem and assume that someone out there has relevant tools, maybe built into some sort of development environment. Sounds expensive and maybe hard to find, though.

I was wrong; writing this didn't help me sort it out. Unless this entry prompts one of my readers to say "You idiot! Why don't you just <answer>?".

Woohoo! I just came from a code review where I made enough of a contribution that Sean the QA guy (who runs them) said he's now putting me on the list for *all* of them. (Code reviews are weekly and constrained to be no longer than an hour, so that amounts to a commitment of a couple of hours a week, which seems reasonable to me. I told him that if it was ok with Werner, our manager, it's ok with me.)

The rule had been that the following people attend: the developer whose code is being reviewed (duh), Sean (our only QA person), a random developer, and a random "defender of the faith" (enforcer of coding standards and so on; currently the set is Paul and Werner, but Paul said he wants to groom me for this). When these were set up, I was under the impression that I was part of the "random developer" pool, and I figured I just hadn't been called for one yet. (We've only been doing this for a couple months, and we have about 15 developers.) But apparently that wasn't the case; Sean didn't have me on his list at all, except as a potential review target. The only reason I was at this one is that I asked to be.
(I was involved in the code.)

(There is a tool for randomly selecting older code to review; it crawls the code base and assigns points based on length, comment density, and various measures of code complexity. Since I've written some test code, I could end up as a reviewee, though I'm pretty good about comments and my code isn't very complex.)

The other thing that was cool about this one is that we have a new engineer who was there as an observer, and I was answering most of the questions he was asking. And then another engineer spotted a potential problem (which I immediately recognized as an actual problem)
but the author of the code didn't see what he was saying, but I did, so I acted as "translator". I think I scored some points for that.

Current Mood: accomplished

I just found the following comment in our source code:

// Quark theory move over.

Sadly, I think I really do need to delve into that particular code and understand what's going on... I wonder what I'm in for.

Current Mood: nervous

Monica

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

(no subject)

(no subject)

simple matter of programming?

egoboo

cryptic comments

Expand Cut Tags

Syndicate