Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]
Groups > comp.lang.java.programmer > #31527
| From | Martin Gregorie <martin@address-in-sig.invalid> |
|---|---|
| Newsgroups | comp.lang.java.programmer |
| Subject | Re: Return of the Applets? |
| Date | 2015-04-07 20:22 +0000 |
| Organization | A noiseless patient Spider |
| Message-ID | <mg1ear$7s8$1@dont-email.me> (permalink) |
| References | (9 earlier) <mfv6j3$n7p$1@dont-email.me> <mg0m3n$qb4$1@dont-email.me> <mg0qhd$shj$1@dont-email.me> <mg0uek$ubn$1@dont-email.me> <mg13bf$4n7$1@dont-email.me> |
On Tue, 07 Apr 2015 13:16:20 -0400, Jerry Stuckle wrote:
> Sure. But the documentation should be much more than what javadocs and
> similar tools generate. Most programmers (especially Java programmers)
> are quite skimpy on the doc they generate.
>
Agreed - both points.
> Full doc includes not only the method name, parameters and return type,
> but any constraints on each of those parameters and the return value. It
> also contains a description of the processing it does, other methods
> this one calls, and other methods which call this one.
>
Indeed. In Java I think the standard class library documentation sets a
reasonable standard that everybody should aim for. As a personal foible,
I tend to regard the package, class, and method level comments as
'documentation' and think these should be written to include the stuff
that I, as a programmer, want to see if I'm going to use them. This means
that comments inside a class or method are not tagged for javadocs use,
principally because when I tried that, the result wasn't terribly
readable.
Same goes for C, where the manpages set a reasonable standard and some of
the tools allow a similar approach to Java - a comment at the top of a
source file is effectively a class-level comment while comments in front
of function declarations have the same content as a Java method level
comment. If a C documentation tool is any good it can use the prototype
or the actual function declaration to generate the API description just
as javadocs does: asking the programmer to do this just wastes his time
and invites errors.
> Very little of this shows up in java documentation.
>
If it doesn't then IMO the programmer and the code reviewers both did a
bad job.
>>> And BTW - you can access serial ports from many different languages,
>>> and TCP/IP from Fortran or COBOL. You just need the right libraries.
>>>
>> Some of these languages, e.g. Fortran and COBOL, don't have these
>> features in their standard libraries (where they even have a standard
>> library). Sure, if they can call external functions you can write
>> extensions, in assembler if necessary, but that isn't part of the
>> language and so shouldn't appear in the language metrics:
>>
>>
> Java can't call TCP/IP either, without native-OS libraries. The only
> difference is these libraries are supplied with the JVM.
>
Of course, but like C, this stuff is in the standard libraries and well
documented. The O'Reilly 'Lion' book may be old, but its still a
worthwhile part of every *NIX programmers toolkit.
For this discussion I think its fair to make a distinction between a
language's standard library and any locally written or 3rd party
libraries: the standard library counts as part of the language because it
and its documentation are there and available once the compiler is
installed while locally written/third parties don't count as part of the
language because they require extra time/effort/money to acquire, learn
and use.
> It's pretty simple. As part of the documentation, programmers indicate
> the number of LOC in the function/method. We've always kept a running
> total, and used that against our design metrics to see how close we are
> to the estimated workload.
>
OK
> Source_lines is not a good metric; it isn't unusual to have a long
> source line span multiple lines in the file. And occasionally you'll
> have more than one statement on the same line. For instance:
>
Indeed: thats why I suggested that:
commentlines = sourcelines - statements
> if (i == 3) return 5;
> else return 6;
>
> Depending on how you write it, this could be two, three or four LOC.
> How do you count it? You can't do it with a simple line counter;
>
Sure, but for languages that use semicolons, counting them or, better,
counting lines that contain semicolons gives fairly reasonable results:
"good enough for government work" as an ex-army helicopter flying
instructor used to say.
> BTW - I usually count it as 3 lines (the "else" is not required), but
> that needs to be determined as part of the project documentation so
> everyone is on the same page. But that doc may say to include the
> "else", even though it is not strictly required at this time, for
> consistency.
>
... and don't lets get into the problems of counting
if (cond) {
statement;
versus
if (cond)
{
statement;
}
As I said, semicolon counting isn't all bad: in these cases it gives the
same answer even if it opens up additional cans of worms with 'for'
statements.
Similarly, though I've never tried it, counting full-stops at the end of
lines would probably work for COBOL. this method wouldn't be confused by
fullstops in data item pictures or decimal points in numeric literals,
and would correctly say that an indexed READ or a SEARCH statement was a
single statement even if it was spread over several lines as is commonly
done. Comments are fairly straight forward too: just count NOTE
statements and all following lines that don't end with a full stop as
well as lines with an asterisk as the first non-numeric, non-whitespace
character.
--
martin@ | Martin Gregorie
gregorie. | Essex, UK
org |
Back to comp.lang.java.programmer | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread
Re: Return of the Applets? Jerry Stuckle <jstucklex@attglobal.net> - 2015-04-05 09:46 -0400
Re: Return of the Applets? Jeff Higgins <jeff@invalid.invalid> - 2015-04-05 13:12 -0400
Re: Return of the Applets? Jerry Stuckle <jstucklex@attglobal.net> - 2015-04-05 15:14 -0400
Re: Return of the Applets? Arne Vajhøj <arne@vajhoej.dk> - 2015-04-05 16:41 -0400
Re: Return of the Applets? Jerry Stuckle <jstucklex@attglobal.net> - 2015-04-05 16:54 -0400
Re: Return of the Applets? Arne Vajhøj <arne@vajhoej.dk> - 2015-04-05 17:08 -0400
Re: Return of the Applets? Jerry Stuckle <jstucklex@attglobal.net> - 2015-04-05 17:17 -0400
Re: Return of the Applets? Arne Vajhøj <arne@vajhoej.dk> - 2015-04-05 17:30 -0400
Re: Return of the Applets? Jerry Stuckle <jstucklex@attglobal.net> - 2015-04-05 17:42 -0400
Re: Return of the Applets? Arne Vajhøj <arne@vajhoej.dk> - 2015-04-05 17:52 -0400
Re: Return of the Applets? Jerry Stuckle <jstucklex@attglobal.net> - 2015-04-05 18:17 -0400
Re: Return of the Applets? Luuk <luuk@invalid.lan> - 2015-04-06 11:26 +0200
Re: Return of the Applets? Joshua Cranmer 🐧 <Pidgeot18@verizon.invalid> - 2015-04-06 13:23 -0500
Re: Return of the Applets? Jerry Stuckle <jstucklex@attglobal.net> - 2015-04-06 15:09 -0400
Re: Return of the Applets? Joshua Cranmer 🐧 <Pidgeot18@verizon.invalid> - 2015-04-06 17:33 -0500
Re: Return of the Applets? Jerry Stuckle <jstucklex@attglobal.net> - 2015-04-06 17:44 -0400
Re: Return of the Applets? Joshua Cranmer 🐧 <Pidgeot18@verizon.invalid> - 2015-04-06 19:10 -0500
Re: Return of the Applets? Jerry Stuckle <jstucklex@attglobal.net> - 2015-04-06 20:03 -0400
Re: Return of the Applets? Joshua Cranmer 🐧 <Pidgeot18@verizon.invalid> - 2015-04-06 21:36 -0500
Re: Return of the Applets? Jerry Stuckle <jstucklex@attglobal.net> - 2015-04-07 09:11 -0400
Re: Return of the Applets? Martin Gregorie <martin@address-in-sig.invalid> - 2015-04-06 23:25 +0000
Re: Return of the Applets? Jerry Stuckle <jstucklex@attglobal.net> - 2015-04-06 19:59 -0400
Re: Return of the Applets? Martin Gregorie <martin@address-in-sig.invalid> - 2015-04-07 13:29 +0000
Re: Return of the Applets? Jerry Stuckle <jstucklex@attglobal.net> - 2015-04-07 10:45 -0400
Re: Return of the Applets? Martin Gregorie <martin@address-in-sig.invalid> - 2015-04-07 15:51 +0000
Re: Return of the Applets? Jerry Stuckle <jstucklex@attglobal.net> - 2015-04-07 13:16 -0400
Re: Return of the Applets? Martin Gregorie <martin@address-in-sig.invalid> - 2015-04-07 20:22 +0000
Re: Return of the Applets? Jerry Stuckle <jstucklex@attglobal.net> - 2015-04-07 17:03 -0400
Re: Return of the Applets? Leif Roar Moldskred <leifm@huldreskog.localdomain> - 2015-04-07 11:34 -0500
Re: Return of the Applets? Jerry Stuckle <jstucklex@attglobal.net> - 2015-04-07 13:18 -0400
Re: Return of the Applets? Leif Roar Moldskred <leifm@huldreskog.localdomain> - 2015-04-07 12:40 -0500
Re: Return of the Applets? Jerry Stuckle <jstucklex@attglobal.net> - 2015-04-07 17:06 -0400
Re: Return of the Applets? Martin Gregorie <martin@address-in-sig.invalid> - 2015-04-07 20:28 +0000
Re: Return of the Applets? Jerry Stuckle <jstucklex@attglobal.net> - 2015-04-07 17:11 -0400
Re: Return of the Applets? Martin Gregorie <martin@address-in-sig.invalid> - 2015-04-07 23:00 +0000
Re: Return of the Applets? Jerry Stuckle <jstucklex@attglobal.net> - 2015-04-07 19:25 -0400
Re: Return of the Applets? Joshua Cranmer 🐧 <Pidgeot18@verizon.invalid> - 2015-04-06 13:09 -0500
csiph-web