Opinions wanted on source style

[Tarkin]

Hello all,

I'm writing my latest whiz-bang app.
I'm extending javax.servlet.Filter, and in the
course of extending, I'm (naturally) adding
some convenience methods.

As a matter of style, but beyond personal
preference, does one put these 'new' methods
before the overridden methods, or after?

My hunch is to put them before, as a reader
familiar with Filter knows that init(), destroy(),
and doFilter(...), have to be in there _somewhere_,
and putting my non-standard methods first shouts,
'Here I am! Read me! Look what I do!!'?

But, is more 'traditional', or precedented, to put
these methods after init(), destroy(), and doFilter(...)?
That seems to more reflect the object pattern- in
that, I'm defining the overridden methods from
the base class first, than adding my 'extended' methods.

Opinions appreciated.

TIA,
Tarkin

 

[Mike Schilling]

Hello all,

I'm writing my latest whiz-bang app.
I'm extending javax.servlet.Filter, and in the
course of extending, I'm (naturally) adding
some convenience methods.

As a matter of style, but beyond personal
preference, does one put these 'new' methods
before the overridden methods, or after?

My hunch is to put them before, as a reader
familiar with Filter knows that init(), destroy(),
and doFilter(...), have to be in there _somewhere_,
and putting my non-standard methods first shouts,
'Here I am! Read me! Look what I do!!'?

But, is more 'traditional', or precedented, to put
these methods after init(), destroy(), and doFilter(...)?
That seems to more reflect the object pattern- in
that, I'm defining the overridden methods from
the base class first, than adding my 'extended' methods.

Opinions appreciated.

People learning about your classes will probably start with the Javadoc,
whose index alphabetizes them anyway. If I were you, I'd concentrate on
helpful and complete Javadoc comments describing the added methods both at
the class level comments and for each individual method.

 

[Tarkin]

People learning about your classes will probably start with the Javadoc,
whose index alphabetizes them anyway. If I were you, I'd concentrate on
helpful and complete Javadoc comments describing the added methods both at
the class level comments and for each individual method.

DOH! Excellent point. I keep thinking I
can put off Javadoc 'until later'. Now
where's that Javadoc trail....

Thank you,
Tarkin

 

[Daniel Pitts]

DOH! Excellent point. I keep thinking I
can put off Javadoc 'until later'. Now
where's that Javadoc trail....

Thank you,
Tarkin

I use an IDE which lets me easily jump around between methods, without
even having to know their relative location. I don't javadoc as much
as I should, but thats not exactly related

I usually look only at helper methods if I see them called, and don't
know what they do (hopefully the name tells me what they're supposed
to do)... IntelliJ IDEA will let me jump right to it, so order doesn't
matter so much.

 

[Lew]

I don't javadoc as much
as I should, but thats not exactly related

Javadocs should, at the latest, be written with the classes and methods. In
interface-driven design you'll javadoc the interface then write the method
signatures. Most IDEs will carry the Javadocs into the implementing classes
for you, otherwise the clipboard works well.

It is absolutely unnecessary and arguably Evil to put off Javadocs until
later. There's a case to be made for doing them first. Procrastination in
this matter is like procrastination in writing exception-handling and
out-of-bounds domain checks, stupid, irresponsible acts of sabotage.

 

[Daniel Pitts]

Javadocs should, at the latest, be written with the classes and methods. In
interface-driven design you'll javadoc the interface then write the method
signatures. Most IDEs will carry the Javadocs into the implementing classes
for you, otherwise the clipboard works well.

It is absolutely unnecessary and arguably Evil to put off Javadocs until
later. There's a case to be made for doing them first. Procrastination in
this matter is like procrastination in writing exception-handling and
out-of-bounds domain checks, stupid, irresponsible acts of sabotage.

Then there is Test-Driven-Development in which documentation is done
by the test cases, rather than javadoc. TDD seems at odds with IDD,
in at least as much that TDD dictates you write the minimum about of
code to make your test pass. This would preclude writing an interface
first, but helps prevent premature generalization. You'd indroduce an
interface iff your tests are currently passing, and it would reduce
complexity.

Granted, TDD isn't as useful for open API development, but extremely
useful for solving use-cases and evolving code.

 

[Lew]

Then there is Test-Driven-Development in which documentation is done
by the test cases, rather than javadoc. TDD seems at odds with IDD,
in at least as much that TDD dictates you write the minimum about of
code to make your test pass. This would preclude writing an interface
first, but helps prevent premature generalization. You'd indroduce an
interface iff your tests are currently passing, and it would reduce
complexity.

Granted, TDD isn't as useful for open API development, but extremely
useful for solving use-cases and evolving code.

One could argue, and your experience seems to support, that different design
paradigms (IDD, TDD, cycles of prototypes, ...) are like different code
idioms: each has a niche or value for certain circumstances. One should have
a full toolbox, not just a hammer.

 

[Daniel Pitts]

One could argue, and your experience seems to support, that different design
paradigms (IDD, TDD, cycles of prototypes, ...) are like different code
idioms: each has a niche or value for certain circumstances. One should have
a full toolbox, not just a hammer.

Unless you're only dealing with nails.

 

[Tarkin]

Javadocs should, at the latest, be written with the classes and methods. In
interface-driven design you'll javadoc the interface then write the method
signatures. Most IDEs will carry the Javadocs into the implementing classes
for you, otherwise the clipboard works well.

It is absolutely unnecessary and arguably Evil to put off Javadocs until
later. There's a case to be made for doing them first. Procrastination in
this matter is like procrastination in writing exception-handling and
out-of-bounds domain checks, stupid, irresponsible acts of sabotage.

Were I working for anyone else but myself,
or if the code was any other release schedule
than 'Real Soon Now', I would agree with 'Evil'.

I've seen plenty of Javadoc that told me not
one iota of WTF the code _does_. I fully
intend to *not* release any sort of Javadoc
that just includes the information I could
have gleaned from looking at a method
signature or class constructor. For the
most part, I look to Java's Javadocs as my
personal 'gold standard'.

At my skill level, I can't afford _not_
to do exception checking, so not coding
it in is not an option :^)

IDE's have been bandied about, but I am
working with constrained resources...my
test server is pIII ~800MHz pc running
Debian (but jdk 1.5.something (11?)),
w/ 256 MB of RAM. I don't dare run X
+ a window manager on it, since also
has Postgres and MySql. My other pc,
where I do have X + KDE + NetBeans
only has 512 MB. Needless to say,
NetBeans slows up when I have the 7
tabs I need opened up in Firefox.

So mostly I develop in vi on the server,
and use my other machine to watch log
files via ssh and see the fruits of
my labors in Firefox.

However, I am filing your and Daniels'
suggestions away as 'good', if not best,
'practices'.

Thank you,
Tarkin

 

[Lew]

Were I working for anyone else but myself,
or if the code was any other release schedule
than 'Real Soon Now', I would agree with 'Evil'.

The first point /might/ let you get away with it, but the second is no excuse.
I am on the tightest schedules you can believe and still Javadoc everything
as I write it. It becomes the same as writing the code.

Whether you agree with the assessment or not does not change how Evil it is.

I've seen plenty of Javadoc that told me not
one iota of WTF the code _does_.

I've seen plenty of code that does not one iota of what it should. This is
not a reason not to write code, either.

I fully intend to *not* release any sort of Javadoc
that just includes the information I could
have gleaned from looking at a method
signature or class constructor.

Javadocs live independently of source. They organize information differently
from source. They cross-link the information. There is no comparison between
Javadocs and the source from which they were generated.

Javadocs are for when you don't have the source at hand or don't want to go to
it or need information packaged more usefully than in source comments.

They also comment the code nicely. Double duty, but different duties. They
aren't equivalent.

Does not excuse lack of comments or documentation.

At my skill level, I can't afford _not_
to do exception checking, so not coding
it in is not an option :^)

At any skill level this is true. From your statement here I would think you
are a master. That is the sort of thing a true master would say.

IDE's have been bandied about, but I am
working with constrained resources...my
test server is pIII ~800MHz pc running
Debian (but jdk 1.5.something (11?)),
w/ 256 MB of RAM. I don't dare run X
+ a window manager on it, since also
has Postgres and MySql. My other pc,
where I do have X + KDE + NetBeans
only has 512 MB. Needless to say,
NetBeans slows up when I have the 7
tabs I need opened up in Firefox.

So mostly I develop in vi on the server,
and use my other machine to watch log
files via ssh and see the fruits of
my labors in Firefox.

Get Ant.

 

[Tarkin]

The first point /might/ let you get away with it, but the second is no excuse.
I am on the tightest schedules you can believe and still Javadoc everything
as I write it. It becomes the same as writing the code.

Whether you agree with the assessment or not does not change how Evil it is.


I've seen plenty of code that does not one iota of what it should. This is
not a reason not to write code, either.


Javadocs live independently of source. They organize information differently
from source. They cross-link the information. There is no comparison between
Javadocs and the source from which they were generated.

Javadocs are for when you don't have the source at hand or don't want to go to
it or need information packaged more usefully than in source comments.

They also comment the code nicely. Double duty, but different duties. They
aren't equivalent.

Does not excuse lack of comments or documentation.


At any skill level this is true. From your statement here I would think you
are a master. That is the sort of thing a true master would say.





Get Ant.

I am on the tightest schedules you can
believe and still Javadoc everything
as I write it.

Oops.. the 'Real Soon Now' was supposed
to be sarcasm. This thing is still in it's
infancy. It's got a ways to go, there's no
customer, no demand, and the code changes
hourly. No excuse for developing good habits,
I know, especially if I ever do want to work
for someone else, have customers and/or
repeat business, or not have my source
laughed off of a free OSS server.

Get Ant.

At this point, a two-line bash script
gets 'er done. All of the stuff I'm
writing is one package, around a dozen
or so individual files, and a few of those
are either abstract or interfaces. I
really don't expect more than another
dozen files. A nice Ant script is
another bridge I can cross if a)
I ever finish this thing and b) I
ever decide to release it.

My original question reveals a carryover
of a mindset from C, where line-by-line
comments are necessary in some parts of
the code, and reading the source is about
the only way to figure out what it does.
I guess if I were writing library or code
I expected to be released, it would be on
me to write man or info pages or something
to document it. In any event, where and when
I could, I would consciously write new(er)
function definitions, or functions that
cryptic names, toward the top of the file,
so that when I came back to it after
an hour/day/week/month, I wouldn't have to
scroll through functions I was thoroughly
familiar with or had intuitive names. But
with Java, there is Javadoc, and other than
laziness, there is no reason not to use it.
I think I was looking at this through C-tinted
lenses...with proper Javadoc, the only
sources people are likely to read or be
interested in are the Abstract classes.

Thank you,
Tarkin