Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]
Groups > comp.lang.java.programmer > #39798
| Path | csiph.com!news.mixmin.net!eternal-september.org!reader01.eternal-september.org!.POSTED!not-for-mail |
|---|---|
| From | Wayne <wayne@nospam.invalid> |
| Newsgroups | comp.lang.java.programmer |
| Subject | Re: What Makes for Good Comments? (Part 3 of 4) |
| Date | Thu, 28 Jul 2022 11:36:12 -0400 |
| Organization | A noiseless patient Spider |
| Lines | 40 |
| Message-ID | <tbuadc$355ho$1@dont-email.me> (permalink) |
| References | <tbt0m5$2q0vv$1@dont-email.me> <tbtt22$315jg$1@dont-email.me> |
| MIME-Version | 1.0 |
| Content-Type | text/plain; charset=UTF-8; format=flowed |
| Content-Transfer-Encoding | 7bit |
| Injection-Date | Thu, 28 Jul 2022 15:36:12 -0000 (UTC) |
| Injection-Info | reader01.eternal-september.org; posting-host="49f0176316dcfcdda6a994404f5a3049"; logging-data="3315256"; mail-complaints-to="abuse@eternal-september.org"; posting-account="U2FsdGVkX181PPLA3WtY5WfCT076slGsEEns1f5Ul1A=" |
| User-Agent | Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:102.0) Gecko/20100101 Thunderbird/102.0.3 |
| Cancel-Lock | sha1:Ww/jrCsFWhzz/t0Ol63+cMn1u1s= |
| Content-Language | en-US |
| In-Reply-To | <tbtt22$315jg$1@dont-email.me> |
| Xref | csiph.com comp.lang.java.programmer:39798 |
Show key headers only | View raw
On 7/28/2022 7:48 AM, Martin Gregorie wrote: > On Wed, 27 Jul 2022 23:44:04 -0400, Wayne wrote: > > IME and IMO too, a good start for writing any Java class is to create a > document, which should be held in a directory hierarchy where it will be > once its content has been expanded to contain executable Java code. It > should contain: > > - a class-level comment describing the purpose of the class and anything > else somebody using it should know about the class as a whole. This > should be followed by a skeletal class definition, i.e. the class > declaration, which should include constants defined and exposed by the > class and possibly some of the more important class-level variables it > contains. > > - the class body should contain declarations of the public methods the > class exposes, each preceded by a method-level comment describing the > method's function and anything else a caller should know about its call > parameters and return value. > > - the document header should include the package declaration and any > 'import' statements needed for it to compile. > > - this class definition must compile and produce clean, easily readable > and understandable output when run through javadoc. > ... Exactly right. This is how I brainstorm my code, by creating skeleton classes with stub public methods. One can easily see the overall structure and change it around, perhaps playing with several different architectures before implementing any stubs. And at that point, after creating initial unit tests and having everything compile, I like to put in "what" comments as pseudocode for the implementation, which I remove as I create the code. If I leave off work for another project, the comments show me where I left off. -- Wayne
Back to comp.lang.java.programmer | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread
What Makes for Good Comments? (Part 3 of 4) Wayne <wayne@nospam.invalid> - 2022-07-27 23:44 -0400
Re: What Makes for Good Comments? (Part 3 of 4) Martin Gregorie <martin@mydomain.invalid> - 2022-07-28 11:48 +0000
Re: What Makes for Good Comments? (Part 3 of 4) Wayne <wayne@nospam.invalid> - 2022-07-28 11:36 -0400
Re: What Makes for Good Comments? (Part 3 of 4) "e.d.pro...@gmail.com" <e.d.programmer@gmail.com> - 2022-08-01 04:40 -0700
csiph-web