Fog Creek Software
Discussion Board


I would like to see what the general opinion is on the topic of disclosure about your programming work.  Here is a situation I encountered a few weeks ago.

I'm an independent contractor currently working on a desktop Java application. I am the only person working on it. For the most part, the requirements and design of this app were done well, so I had a really good idea about what the app needed to do. It wasn't designed down to the absolute lowest level (it didn't need to be) before I began implementing it. During implementation, I encountered situations that were not covered explicitly in the design. Happens to everyone.

In many cases, the behavior was obvious. But in some cases, it was not. I'd ask around for opinions from the other employees, but sometimes these issues were so obscure, it was hard to get feedback.

So, as an experienced professional, I made a reasonable implementation choice and documented the issue, the solution, and the implications of this solution, if any. Often these issues had to do with memory vs. performance, or deviating from the specs or not.

The project was wrapping up, and I wrote a "release notes" document that went into excruciating detail about these issues. Then I held a meeting to go over these things to see if anyone wanted changes to the ways I'd chosen. They suggested some changes, no big deal.

But, during the meeting, I kept getting a feeling that my clients were judging my work badly because I was pointing out all of the "questionable points" about what I implemented. Since I was only talking about these areas, it might have seemed like my code was fraught with problems. Well, no, it was only specific parts.

Since I'm a contractor and won't be here to maintain or upgrade this code, I thought it was professional of me to do this. Some of the code gets pretty complicated. Yet, I left the meeting wondering if I should have just kept quiet, or just documented it in the code. I wonder if I damaged my reputation and looked incompetant, when in fact, I was attempting to be a responsible contractor. If I was a regular employee, I probably wouldn't have done this because they could always come back to me to fix it later.

What do you think about disclosing the design choices of your code?  How much? How do you disclose it (doc? comments in code?)

Is it unethical not to say anything?

Lauren B.
Thursday, May 29, 2003

I submit an alternative interpretation...

Is it possible that the perceived negative feedback from your "peers" was due to the fact that you spent what appears to be a considerable amount of time documenting a problem when instead you could have brought it to someone's attention immediately and possibly had it addressed?

I'll admit my bias up front. The process you described is not the way we work here. If any of the developers that work in my group had done what you have I would have complimented them on their work ethic and then asked them never to do it again.

I'll give you a, possibly heretical, view of software development. Design isn't the most important thing. Good tools isn't the most important thing. Coding "skillz" isn't the most important thing. Communications is the most important thing.

In all but the rarest organizations, a design is a "dead" document. It's not alive in that no one is likely spending any time updating it. Hell, many on the team are probably not even referring to it. The collective group "understanding" of the design is what's important. It is what's alive. You have to keep your ear to this, not to the document.

As I said, some may find this view heretical. :)

At any rate, I applaud your dedication in flushing out a possible issue. Next time, I would suggest escalating the issue as soon as possible.

Thursday, May 29, 2003

Lauren did mention trying to get feedback from other employees in the original message. 

Having worked as a contractor in the past, I wouldn't be so quick to lay the communication problems at Lauren's feet... it may have been like trying to talk to a brick wall and you can't just stop work and wait for a couple weeks until the people you're waiting to hear back from answer your requests.

Personally, given a similar situation, I think a good solution would a quick overview (not super detailed) release document and skip the meeting.

Mister Fancypants
Thursday, May 29, 2003

Oops, mea culpa.

Hitting a brick wall when trying to communicate what could be a critical project issue is not something that tends to build a lot of trust in a development team.

Faced with that situation you're choices really are:

Potential showstopping issue: Yell until someone listens. Take hostages. In this case, a document is not going to be enough anyway so don't bother.

Garden variety serious: Inform team leaders immediately. Submit a defect report.

Minor: Refactor the code yourself if time permits. Otherwise, inform team leaders and let them decide.

I stand by my previous assertion that documentation should be looked at as a last resort. If you assume that any document you write is not going to be read you won't go far wrong. :)

Thursday, May 29, 2003

I think you are talking about sharing nitty gritty details with the decision-making clients on a project...  As a developer, one is always looking at 100 different ways a project/application can go awry. e.g. it might not work under Netscape 4.x, what happens if they don't have the right runtime installed, what happens if they are running the Dutch version of Windows 95 on 640 by 480, etc. (as Joel has pointed out in his articles).

Sometimes clients don't need or want to hear about this stuff... especially non-technical ones.  They are concerned about their own business issues.  So maybe don't shoot yourself in the foot with nitty gritty attention to what might be a future problem.

Metaphorically speaking... when you buy a car and drive away from the lot... does the salesman say "now when you are driving down the road in rain, you can use intermittent wipers and adjust the variability setting right here... make sure you leave the tank full if you leave the car outside in Winter time... also make sure you get a full oil change periodically", etc.  Or does the salesmen say "we've built an excellent car for you and we hope you enjoy the ride" ?

So maybe if you are wrapping up the meeting leave it at "we are ready for deployment and it's a highly stable and high quality application... be sure to let us know if there are any issues that have not been identified by the extensive testing that has already been done", etc.

Thursday, May 29, 2003

It sounds like you did a really thorough job covering the potential issues. It's possible that a less thorough treatment of the issues would have satisfied the client.

As for creating a positive impression of your work without sweeping issues under the rug, what about starting a meeting off with a demo or some other opportunity to show off the success of the app? If you start things off by demonstrating that you've produced what the client wanted, they may be in a better mood when you move on to talking about issues.

Beth Linker
Thursday, May 29, 2003

I would've pointed out where they were, what they were, and given one or two examples, then moved on. I don't think it's worth going through them in excruciating detail unless they affect contractual acceptance criteria.


Thursday, May 29, 2003

Lauren, I think you acted professionally.  You acquitted yourself with honor.

In my opinion, I think the situation would have fared better if you'd talked to the *client* about these problems as they came up, rather than fellow developers.  If I were the client, I would have wanted to know about these issues early.  Plus, this would have spread out the reports of problems over time, rather than telling the client all at once at the end of the project.

If the issues were purely technical -- e.g., they didn't affect the business value of the application -- then I think you shouldn't have told the client, at least not in detail.  "Release Notes" would have been fine.

Either way, I think you handled it very responsibly.

Brent P. Newhall
Thursday, May 29, 2003

My rule of thumb for iffy design decisions is pretty basic.
If the client has a technical/programmer person to liason  with then talk everything over with them.
If it doesn't affect the specs, I dont tell them.
If it affects the specs in small ways that *I* dont judge to be at all important, I dont tell em.
If it affects the specs in bigger ways, I mention the need to alter the specs, and discuss how important the specific feature/requirement is.  The basic idea is that we discuss the importance of implementing it relative to the cost of doing so.  Mostly I find that changes are fine <g> particularly when compared, for instance, to the cost of rewriting the jvm/web server/whatever so that what they need is possible.
If it has a huge effect on the specs I assume Im being stupid and missing something :)

Thursday, May 29, 2003

If you were doing a desktop Java app, then I can see where you would have problems.

If the client personnel were not software developers, you should not have gone into the nitty gritty details with them, because they wouldn't understand the significance.

Thursday, May 29, 2003

Excellent suggestions, thanks.

Actually, the team I presented this to was all technical (including the people who will be supporting this app when I'm done with the contract). The corporate priorities shifted between when I started the contract and now. Initially, all of these folks were working on this system with me, because it was mission critical. When priorities changed, they all got pulled off to work on the latest "gotta have it now" system. So I think part of their indifference was the fact that they're focused on something else now.

I really liked FullNameRequired's guidelines. That is very useful.

Lauren B.
Friday, May 30, 2003

This is really a consulting and political situation. This situation illustrates the difficulty of providing hard core facts to people who aren't intellectually or emotionally capable of dealing with facts. This category includes many managers (even supposedly born and bred technical managers), marketers, and executives who came up through a business track rather than doing something constructive and creative for a living.

Also, some techies who work full time for the client may sieze any admission of your "weakness" (AKA lack of omnisience) as evidence of your incompetency. Even though they usually know better.

As a developer, technical pro or engineer, we are paid to resolve problems. But you cannot talk about your work in the terms that competent engineers are used to talking about it when you are in a vendor-client relationship.

Sorry for shouting. Many programmer types NEVER get this.

This is, in my view after working 10 years as a consultant, solely an intellectual failing on the part of just about everyone who is not a smart technical person. :-) 

You *must* learn to baby certain people who are in the client's position. And this weakness/end user character deficiency (am I laying it on too thick? :-) )  is universal.

This natural bias in non-technical people to look down on honest statements of real life constraints tends to favor BS artists in our industry. The glad hand smooth talker types that say "noooo problem" are generally far ahead of the Calvinistic self sacrificing programmer types who voluntarily wear haircloth when their code screws up.

This sort of relationship issue is the domain of the consultant-to-consultant authors like Janet Ruhl, Jerry Weinberg, et al.
Good luck on you. This is how I see it.

Bored Bystander
Friday, May 30, 2003

Bored, I'm afraid to seriously consider another IT job for that reason.  I'm sorta messed up in the way I relate to other programmers because I basically evolved to talk out my ass, and at some point I lost the some of the ability to know when I'm doing it.

I've met one company in the last 2 mo. that seemed to be smart & hungry (I used one of their products), and they seemed to like me, but sadly they were too far away for me to work there.  Not that I want to work anywhere; I'm spending all my time learning algorithms and some esoteric things, because I need to control the terms of my technical relationships more. 

Maybe I am wrong about programmer groups; I like meritocracy but business can't fulfill that, opensource communities can.  Anyway, enough offtopic rambling, sorry.

Saturday, May 31, 2003

*  Recent Topics

*  Fog Creek Home