directory-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ole Ersoy <ole.er...@gmail.com>
Subject Re: [CONSTANSTS] Conventions and Update
Date Sun, 15 Apr 2007 01:44:28 GMT


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


Mime
View raw message