Path: csiph.com!usenet.pasdenom.info!gegeweb.org!eternal-september.org!feeder.eternal-september.org!mx04.eternal-september.org!.POSTED!not-for-mail From: Eric Sosman Newsgroups: comp.lang.java.programmer Subject: Re: unchecked conversion warning. Date: Fri, 01 Jun 2012 20:24:30 -0400 Organization: A noiseless patient Spider Lines: 49 Message-ID: References: <3s7cs7hd18l0ffci55ns0286n4lc4cutlu@4ax.com> <24hfs7hqsr75jmqgk87jcpfg85kif7nhuo@4ax.com> Mime-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit Injection-Date: Sat, 2 Jun 2012 00:24:34 +0000 (UTC) Injection-Info: mx04.eternal-september.org; posting-host="03ebLEozl+tXCe7JS60Feg"; logging-data="12061"; mail-complaints-to="abuse@eternal-september.org"; posting-account="U2FsdGVkX189BEBJcTvA/r5p3v2o15hJ" User-Agent: Mozilla/5.0 (Windows NT 5.1; rv:12.0) Gecko/20120428 Thunderbird/12.0.1 In-Reply-To: Cancel-Lock: sha1:yF3aW55sWZyS3L3sKgJCOfVlxYQ= Xref: csiph.com comp.lang.java.programmer:14997 On 6/1/2012 7:44 PM, Patricia Shanahan wrote: > On 6/1/2012 10:54 AM, Eric Sosman wrote: >> On 6/1/2012 11:44 AM, Patricia Shanahan wrote: >>> On 6/1/2012 7:41 AM, Jim Janney wrote: >>>> Eric Sosman writes: >>>> >>>>> (JavaDoc is both a blessing and a curse: It's a blessing in that >>>>> developers *are* encouraged to write documentation, and it's a curse >>>>> in that *developers* are encouraged to write documentation. ;) >>>> >>>> If I ever found myself screening applicants for a programming job (not >>>> something that's ever likely to happen) I would be very tempted to ask >>>> them to write a short essay. If you can write clearly then I know you >>>> can think clearly too. >>>> >>> >>> Help! I hate writing English essays, and was never very good at it. >>> >>> Perhaps I picked the wrong career, but it's a little late now that I'm >>> retired on the proceeds of my ill-chosen career path. I needed to know >>> that I would not be good at programming back in 1970. >> >> Pull the other one; it's got bells on. >> > > Yes, I'm joking about reconsidering my choice of career, but if getting > a programming job in 1970 had depended on English writing skill, I would > have been rejected - I write much better now than I did then. Aside from pure linguistic tasks -- writing grammatically and correct, spelling words propperly, punctuating well that, sort? of thing -- The developer needs some skill at separating himself from his own context when documenting his artifact. The person who wrote the code participated in the design discussions, knows what approaches were considered and rejected (and why), remembers only too clearly the bugs that were easy to fix and those that kept him awake nights, and is aware that class X began as a bunch of parallel `switch' statements in class Y before refactoring. When he sets out to document class X, he may have a hard time writing in a way that will be intelligible to someone who does not share his prior knowledge. A documentor needs some of the same skills as a teacher, most especially the knack of seeing things from the point of view of a reader not yet versed in them. "Empathy," if you will. -- Eric Sosman esosman@ieee-dot-org.invalid