Emmanuel Lecharny wrote:
Ole Ersoy a écrit :
<snip/>
Incidentally I think we should apply this type of convention
to all java members and variables.
I'm not so incline to this kind of convention. People are smart enough
to figure out what is what with short names.
I agree that most people that look at apache code are smart enough
to ultimately figure out what's going on.
I just saw code like this in the JDNI tutorial
ModificationItem[] mods = ...
Personally I would have stated it:
ModificationItem[] modificationItems = ...
My general convention here is to always, when
there is only one of a type, just lowercase the type,
and it it is a many type (List, Array, etc.) add an
s.
I think code that is written like this is a lot easier to
track and read, and using this type of simple convention
means that everyone will be seeing the same thing.
I recently tried to improve the widget mechanism in Dojo Toolkit,
and Dylan Schieman had used so many abbreviated variables that
it was a huge massive effort just to uncover what he had done.
I think in general we are much better though, and for the most part
all our members and variables are easy to understand.
'i' is self-explicit, for
instance. And the fact is that long variable names (say, above 12 chars)
generate more problems than short ones (mispelling, confusion, case
problem, etc). I have read an interesting study about this aspect, I
don't remember where (may be Writing Solid Code, or a study done by
NASA, can't remember, it was 15 years ago) where it was clearly exposed
that there is a limit for variable length above which the developpers
are likely to generate more bugs ...
When creating an Attribute like this for instance;
Attribute objectClass = new BasicAttribute();
Some call it Attribute oc...
I call it
objectClassAttribute
Why ? Here, you *know* that objectClass is an Attribute, because its
type is Attribute. As we are not using 'vi' anymore (or only from time
to time), you have many ways to get this information.
I know. I just like to have the information right there...so I don't
have to get it. I feel like it makes me more productive. And when
I look at my own code, I immidiately remember what's going on.
And when generating javadoc and other documentation, very often
the additional information on the member is translated into
more complete documentation.
<snip/>
Also, if it were called just objectClass...I might just wonder
whether it's an ObjectClass or Attribute...so by postfixing the
Type we avoid the "What is that thing again?" scenario.
Please, no more hungarian notation ! (I don't know if I should whish
that Soyouz don't come back to earth, and let Simonyi turn around the
planet for ever, to punish him for having added those stupid lpstrch and
zptrpch before or after every variable names ...)
:-) ...
As a rule this convention could be expressed as "Append the Type to
the end of a member". Sometimes it's really really obvious, but as
the code
base grows and more gets added to the file, it becomes less obvious.
Just use common sense,
Yeah - In general I think a small group using common sense works great.
Especially with members comitters as talented as the ApacheDS ones.
Once the team grows and more people start adding code, conventions that
are spelled out so that everyone has as much guidance as possible
helps a great deal in keeping the code base comprehensible for all.
here. If it's not obvious when you write it, then
adopt another name. It should be enough as a convention. If it's not,
then you are lacking of common sense (and be sure that sometime, we are
all fools ...)
Yes that's what I mean - Sometimes really smart people do really
smart things....just that those things are really tricky to uncover
for others.
<snip>
When everyone follows conventions like this, it makes it a lot
easier to read code, because we know what the conventions are,
and thus we can immediately identify what someone is referring to...
You also have to consider anothe relement you are missing : using long
variable names, concatenating many words, could drive the code to be
full of meaningless names : many of us are not english natives, and we
may perfectly abuse the names so badly simply because we are not used to
them. It's more difficult to FU when using a simple name
I agree a little :-) I think just using a convention like call a member
of type Attribute ... attribute or ModifcationItem ...modificationItem
covers 90% of all cases and it's a really simple convention for all to
follow.
The idea is to minimize the amount of time that someone spends getting
create about naming, yet ensure that the name is legible and easy
to understand.
Someone contributing code could easily have 10 ModificationItems
called m1, m2, m3, m4, etc.
and when people start using really short abbreviations
like this all over code gets tough to track.
Not that we do this really. All the code I have seen
is easy to read. This is just to future proof the growth of
the server.
like 'context'
than something like partitionConfigurationServiceContext' which means
nothing at all (this is a clear example extracted from some code I just
committed this afternoon, and I'm not proud of it ... :(
hehe :-) Shame Shame Shame!! The type of convention I use here is
for DirContext...I just call it directoryContext.
I spell it out fully, just to follow a rule. I could just call it
context or ctx, but I deal with so many different type of contexts all
the time (Servlet Contexts, JSF Context, ...) that I find I feel it's
easier on my squirrel nut when seeing directoryContext.
Maybe partitionConfigurationContext would have been good for that one :-)
I think that would have been easy to understand. Someone else could
have called it pcContext...and then the next person has to track it down.
Cheers,
- Ole
