Path: csiph.com!v102.xanadu-bbs.net!xanadu-bbs.net!news.glorb.com!npeer03.iad.highwinds-media.com!news.highwinds-media.com!feed-me.highwinds-media.com!border3.nntp.dca.giganews.com!Xl.tags.giganews.com!border1.nntp.dca.giganews.com!nntp.giganews.com!local2.nntp.dca.giganews.com!nntp.earthlink.com!news.earthlink.com.POSTED!not-for-mail
NNTP-Posting-Date: Fri, 01 Jun 2012 21:35:39 -0500
Date: Fri, 01 Jun 2012 19:36:00 -0700
From: Patricia Shanahan <pats@acm.org>
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:12.0) Gecko/20120428 Thunderbird/12.0.1
MIME-Version: 1.0
Newsgroups: comp.lang.java.programmer
Subject: Re: unchecked conversion warning.
References: <3s7cs7hd18l0ffci55ns0286n4lc4cutlu@4ax.com> <f9064504-3948-43d4-b66e-55434a7a1ed1@googlegroups.com> <24hfs7hqsr75jmqgk87jcpfg85kif7nhuo@4ax.com> <jq8lij$g95$1@dont-email.me> <ydnhauvhz6o.fsf@shell.xmission.com> <RLydnRJ6QcLdflXSnZ2dnUVZ_jWdnZ2d@earthlink.com> <jqavlm$9j$1@dont-email.me> <ubmdnZGU44BDzlTSnZ2dnUVZ_q-dnZ2d@earthlink.com> <jqbmg2$bot$1@dont-email.me>
In-Reply-To: <jqbmg2$bot$1@dont-email.me>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit
Message-ID: <K5WdnemW38th5lTSnZ2dnUVZ_qCdnZ2d@earthlink.com>
Lines: 20
X-Usenet-Provider: http://www.giganews.com
NNTP-Posting-Host: 70.230.202.8
X-Trace: sv3-eT3WO6krjPbUJ5QmN1poz5pIg5DEjsk/fCE5WNfj3qSB9y12DFjrSvJ+agzvriOfNAg7xiScdAf1Mr5!Bv3AUx34D1ICX/t0RNntSVBr9Y6bpqcnloV231Pr/UnvT4D7rBbujIUPlbmpdx3kb3NqRAUd/VWO!/un/3zfxZYENq51QqOlFQ+2tZ0/novSEUU0QthnFITFQ
X-Abuse-and-DMCA-Info: Please be sure to forward a copy of ALL headers
X-Abuse-and-DMCA-Info: Otherwise we will be unable to process your complaint properly
X-Postfilter: 1.3.40
X-Original-Bytes: 2476
X-Received-Bytes: 2617
Xref: csiph.com comp.lang.java.programmer:14998

On 6/1/2012 5:24 PM, Eric Sosman wrote:
...
> 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.

I find it helpful to write unit tests and Javadocs at the same time.
Both require that sort of separation. Both require attention to extreme
and special cases.

Patricia