Time to start the Code Style Discussion

[Essington]

O.K. before we can start building a library that doesn't look too
cobbled together, we need to all decide on code style.

More than just whether we put braces on their own line, this defines
what the best practices of gwt-commons will be.

I have begun a document that will outline the gwt-commons requirements
for code style.

it is as yet un-finished, but we should discuss the contents and build
it up until it is acceptable to everyone.

Remember, what I have started here so far is just a proposal, but we do
need to get this hammered out before we can even start importing any
code into trunk.

-jason

Click on
http://groups-beta.google.com/group/gwt-commons/web/code-style?hl=en -
or copy & paste it into your browser's address bar if that doesn't work.

[ash]

at the moment ur document is very light weight, which pleases me.

im hoping that we dont institute checkstyles and dont become too rigid.

u guys (u & mP) remind me what me what i was like about 6 years ago. i
almost needed counseling b/c i couldnt satisfy my own standards,
conventoins, idioms and practices. so i kindly ask that u let me enjoy
my final year as a software developer and let me believe that my
contributions are worthy<g>.

rgds ash
http://www.gworks.com.au

[ash]

[Robert Hanson]

What about imports? I am a believer in that each import line should be
fully qualified, without a "*". Is anyone truly against doing this?

[Essington]

On Nov 21, 6:43 am, "Robert Hanson" <IamRobertHan...@gmail.com> wrote:
> What about imports? I am a believer in that each import line should be
> fully qualified, without a "*". Is anyone truly against doing this?

That is why that page is up, anyone who sees something missing should
add it.

I also agree, there is never any reason to use package imports.

-jason

[Freller]

As I said, I've posted my comments.

Regards,
Freller

[Essington]

Hey Miroslav,

In regards to the proposed field naming convention - Suffixed with an
underscore '_'

This is not a convention that I use, and appears to be pretty
contentious as a whole, but the explanation for using it seemed sound
to me.

By suffixing your fields with _ you signify their scope (I know that
most IDEs will color them too), and avoid naming conflicts, so you can
continue to use the descriptive name that you have chosen.

private HorizontalPanel linkPanel_;
public void setLinkPanel(HorizontalPanel linkPanel)
{
linkPanel_ = linkPanel;
}
public HorizontalPanel getLinkPanel()
{
return linkPanel_;
}

the underscore also helps prevent inadvertent use (or shadowing) of the
field.

I am certainly not sold on this one, and if the consensus is to skip it
that is fine with me.

I'm pretty used to doing this.panel = panel; to signify whether to use
the field or local variable.

-jason

[Luminari]

I added a section for Documentation. Any good commons library should
enforce good documentation standards.

On private variables:
I think its better just to have all member variables accessed with
this. , then there is no confusion over where they are from, and most
ide's make it very easy to type this.variable.

- Luminari

[mP]

i always use final parameter in my setters to avoid mistakes..

[Robert Hanson]

I have used both an "_" prefix, and "this". I agreed to the "_" in
the doc, but I don't have any real preference.

Rob

[ash]

i have been deliberately silent on the coding style front. there is a
tendency to be overly religious about these things.

moons ago i started programming with dynamic oo languages and developed
a series of conventions and idioms that served me well over time. as i
moved from language to language i would bring these idioms with me.
then 6 years ago i wrote a java book and bruce eckel reviewed it. there
was much that he liked with my use of modeling concepts (i was a member
of otug which evolved the 1st drafts of the uml spec with the 3
amigos). however, bruce gave my conventions a belting and continued to
write a page discourse in his response.

it was that point that i started a journey which later helped me
realise that i was deeply attached to styles and conventions. my code
would once read like logic with road signs to signal semantics. i could
look at no more than a few lines of code and confidently assert things.
was this a good thing? well to me it once was, but it is no longer.

the best argument that i could find on this subject was by bob martin
(uncle bob) who once said: "documentation lies!"
this statement challenged my road signs.

> i always use final parameter in my setters to avoid mistakes..

fine, but realise that all we are doing is protecting ourselves from
ourselves.

my preference is to avoid any noise in code and view elements in their
most distilled form. therefore, i now avoid the use of: _, final, this
unless required for scoping. i use public instance variables and
structs.

the only two conventions that i can currently think of are based on
structural stereotypes:
<name>Utils - for any class utility/non-instantiated class (this is a
booch-ism)
Abstract<name> - for abstract classes

if this troubles u then thats ok, i understand, i have been there.
please feel free to refactor the code that i contribute.

rgds ash
http://www.gworks.com.au

[Robert Hanson]

> i have been deliberately silent on the coding style
> front. there is a tendency to be overly religious about
> these things

I am not religious about coding style, I gave that up long ago.

> my preference is to avoid any noise in code and view
> elements in their most distilled form. therefore,
> i now avoid the use of: _, final

I am pro-final. The final keyword is itself documentation via code.
It also prevents tampering. My philosophy is to be as strict as
possible. This isn't because I want to lock users out, it is because
it makes maintenance easier.

(RE "_": I have no preference on this)

> i use public instance variables and structs.

Same here... public instance variables are bad. If you ever find that
you need to turn the instance variable into a getter/setter to add
some additional functionality you would be stuck.

Remember that there will be a thousand (or more) developers using this
code. So if you provide them the ability to change a final variable,
or access an instance variable directly, they will. ...And you will
never be able to take it back without breaking their code.

Rob

[g.georgo...@gmail.com]

No, underscore I don't like because it not only looks ugly (you won't
see much of that in the JDK sources for instance) but that is what
scoped instances and the protected/private keywords are for.

No on finals either: they bloat the code and just attempt to state that
an argument will not be changed inside the method while this is a big
lie (Ash is right: documentation lies)... Take this example:
someCollection in

public void bet_that_I_can_change_you(final Collection someCollection);

is very severely mutable and the final keyword doesn't do much to
protect someCollection from being altered inside the method. And if you
play nice and actually publish your code as interfaces and hide the
concrete implementations (I hope that to some extent we can achieve
this) then the 'final' keyword is not worth much either. Java solved
this dilemma by not allowing pointers, ** or & references and that's
just as far as you will ever get. Besides, even with that keyword, it
only states the method author's _intention_ to not alter the argument,
that does not mean that the passed object's state in fact has not
changed by its own responsibility... think of an object that increases
a counter everytime equals() is invoked.

[Jason Essington]

personally I don't care what we decide for code style (as long as
there isn't anything too asinine)

but I do think that we should decide on a set style and stick to it,
so that the code base appears to be a cohesive unit.

If everyone does something different, anyone trying to look at or
modify the source will have to wade through everyone's idiosyncrasies
which could become annoying pretty easily.

-jason

[mP]

I always use final for variables, i avoid changing local variable
values(references) most of the time. If a value is truely
changable(mutable) then its not final...otherwise (an immutable
value/ref) it should be marked final. This makes the mutability clear.

Aside from coding style the big issue is what do we bring into the lib.
Coding styles can be fixed/modified once whatevere is sucked in.

[Robert Hanson]

> Take this example: someCollection in
> public void bet_that_I_can_change_you(final Collection someCollection);

When I mentioned wanted to use final it was in reference to
public/protected class properties, not method arguments. I am more
interested in restricting how the outside world can interact with the
class than I am with the inner workings.

As for declaring a method param as final, there are cases where you
might want that. For instance if you need to alter the contents of
the collection inside of an anonymous class. And example might be a
sort routine.

> even with that keyword, it only states the method
> author's _intention_ to not alter the argument

I disagree... but it doesn't really matter as again I am only
concerned with class properties, in particular those of immutable
types.

Rob