BTW, sometimes I choose to use longer names for local variables: see my reimplementation of number to string conversion in o.a.f.util.NumberConverter, which is a new (and large) class I added in the CS branch. I use a few short names here, but not as many as longer names. So you can see that sometimes I find it useful to use longer names. This sort of decision (when to use long or short) should be based on an author's preferences, and not established by fiat.
Notice also the considerable use of nested classes (and interfaces), which tends to make the file longer, but nevertheless encapsulates abstractions in smaller units. True, this file could be sub-divided into smaller files, and I may yet do that. However, I found it convenient to keep it in one file for the initial implementation. On Wed, Oct 26, 2011 at 8:54 PM, Glenn Adams <gl...@skynav.com> wrote: > > > On Wed, Oct 26, 2011 at 8:36 PM, Peter Hancock <peter.hanc...@gmail.com>wrote: > >> >> On Mon, Oct 24, 2011 at 09:05:34PM +0800, Glenn Adams wrote: >> > are you claiming my code is not maintainable by other developers? if so, >> > then please prove it objectively; otherwise, let's stop talking about >> this, >> > and move on with the merge vote >> How would one go about proving objectively that code is not maintainable? >> > > My point is that this is a subjective exercise we are having here, and not > particularly fruitful. It can be done objectively, or at least more > objectively if one wants to take the time to do so. For example, by defining > specific objective metrics and tools that measure those metrics against the > existing code base and against new code. > > But instead of doing that, we are presently dealing with argument by > innuendo. > > >> >> There are many aspects to writing maintainable code, spanning from the >> synax level through to the structuring of classes and modules >> (packages). Importantly we should encourage: >> Code reuse - (using trusted libraries, applying the DRY principle) >> hard to measure objectively >> A consistent style - this may be an emergent aspect of a project and >> choosing guidelines at the start or even retrospectively may be too >> difficult, but we can largely infer the style from the current state. >> An imperfect but consistent style is arguably favorable to >> inconsistency. >> Idiomatic language usage - applying common solutions that leverage the >> constructs of, and the philosophies behind a language (e.g applying OO >> design patterns in Java applications). >> >> I find that writing code that is in keeping with a the style of a >> project and using the language as recommended makes it easier to >> distill the intention of a piece of code from the implementation and >> can lead towards self-documenting code. >> >> The inner workings of FOP are complex and I think that all efforts to >> boost understandability are essential. >> > > It is rather ironic that I find myself being interpreted as somehow trying > to decrease coding understandability, or being interpreted as promoting > idiomatic or inconsistent usage. You should ask some of the hundred or so > developers who have worked under me their opinion about my code. You would > come to a different conclusion. > > I wonder what you think about the code in o.a.f.hyphenation.TernaryTree, > where the author apparently did not know Java, and introduces the libc > functions strcmp, strcpy, and strlen, and which uses the Java char type > (within the String type) for coding tree pointers! > > I also note the author of this file uses short names for (exposed, > non-private) instance variables, such as: > > protected char[] lo; > protected char[] hi; > protected char[] eq; > protected char[] sc; > protected CharVector kv; > > At least in my case, I use long names for instance variables, even when > they are private. > > If you wanted to make a serious case against using short names, you would > start first by analyzing existing FOP usage and using such an analysis to > establish concrete metrics. That would allow objective comparisons to be > made. > > G. > > >> >> Peter >> >> On Wed, Oct 26, 2011 at 12:55 PM, Glenn Adams <gl...@skynav.com> wrote: >> > inline >> > On Wed, Oct 26, 2011 at 7:17 PM, Vincent Hennebert < >> vhenneb...@gmail.com> >> > wrote: >> >> >> >> On 24/10/11 14:05, Glenn Adams wrote: >> >> > On Mon, Oct 24, 2011 at 8:26 PM, Georg Datterl >> >> > <georg.datt...@geneon.de>wrote: >> >> > >> >> >> Hello Glenn, >> >> >> >> >> >>> (2) there is no standard for symbol length documented in FOP >> practice >> >> >>> or enforced by checkstyle; I decline to exchange my choice of >> symbols >> >> >>> with longer symbols simply because you prefer it that way; I have >> >> >>> offered to add comments to my uses, and that is the most I'm >> willing >> >> >>> to do to address this matter; >> >> >> >> >> >> You probably spent more years programming than I am alive, so please >> >> >> excuse >> >> >> me if that’s a stupid question: What is the reasoning/advantage >> behind >> >> >> those >> >> >> short variable names? >> >> >> >> >> > >> >> > First, I don't use short names everywhere. Mostly I just use in local >> >> > variables, but generally not as class variables. >> >> > >> >> > Second, I was trained in Physics and Mathematics, which uses short >> >> > variable >> >> > names (E = M C ^ 2). >> >> >> >> Welcome to the Computer Science world, where longer variable names rule >> >> because they allow to make a program easier to understand and maintain. >> >> >> >> When I read the paper about the total-fit algorithm for breaking >> >> paragraphs into line, I found that the numerous one-letter variable >> >> names were an impediment to understanding it. It was difficult to >> >> remember what concept each variable was associated to. >> > >> > I had no trouble understanding it. In fact, I re-implemented it in Lisp >> > (Scheme), and fixed a few issues in the process, which I reported to Don >> > Knuth and for which he sent me a check for $2.56. See attached file. >> Note >> > that I used long names for (structure) member names and dynamic >> variables, >> > but often short names for local (lexical) variables in this code which I >> > wrote 20 years ago. I haven't changed my style since then, and I don't >> > intend to do so now. >> > >> >> >> >> > Third, I started programming in the 1960s with BAL 360, APL, then >> >> > FORTRAN >> >> > IV. We use short names there. >> >> >> >> Yes, it is very fortunate that the computer world has learnt from those >> >> old days, and moved on to embrace better programming practices. >> > >> > We are apparently in different generations, and this influences our >> > thinking. I am not judging your style, but you seem to be quick to judge >> my >> > style. Personally, I find ideology counterproductive. >> > >> >> >> >> > Fourth, I happen to have a good memory and I have no trouble >> remembering >> >> > the >> >> > meaning of variable names. >> >> > >> >> > Fifth, I find that short names prevents making lines too long and >> gives >> >> > me >> >> > more room for comments. >> >> >> >> By putting only one statement per line it is rare to bump into the 100 >> >> characters per line limit. >> >> >> >> >> >> > Sixth, I am going to be maintaining this code. If anyone has a >> problem >> >> > with >> >> > specific code during a merge or regression, they merely need ask me. >> >> >> >> As Simon has already pointed out, this is not the way it should be in >> an >> >> open-source project. >> >> >> >> >> >> > Seventh, that's just my style, and I assert it is as valid as doing >> it >> >> > with >> >> > long names. >> >> >> >> When I joined the FOP project, I adjusted my style to follow the >> >> project’s practices. It seemed obvious to me to do so, because >> >> a consistent style within a project avoids unnecessary distraction when >> >> wandering through its different parts. I would expect any contributor >> to >> >> do the same. >> >> >> >> >> >> > Eighth, asking me to adhere to an undocumented convention that is not >> >> > otherwise enforced, and for which there is no evidence or analysis of >> >> > having >> >> > been previously followed in FOP contributions is unwarranted. >> >> >> >> There is no documented convention simply because it has never occurred >> >> to anybody in the past that short variable names could be an option. >> >> This is this kind of unwritten convention that everybody takes for >> >> granted. >> >> >> >> >> >> > Ninth, spending time changing variable names is a waste of time when >> I >> >> > could >> >> > be working on adding support for other scripts. >> >> >> >> So someone else is going to have to waste all that time converting >> those >> >> names into more readable ones. That’s a bit unfair, isn’t it? >> > >> > I would advise against anyone wasting their time by changing my names. >> > Indeed, I will likely react very negatively to such an attempt. What you >> > want to do in your code is your business, but don't imagine you are >> going to >> > start rewriting my code to meet your style. Or at least don't do so if >> you >> > wish me to be a part of this team. >> > I would take such an action as a direct affront. >> > If in the indefinite future I am not working on this code, then feel >> free to >> > change it as you like. In the mean time, I'd appreciate a little >> respect. >> > >> >> >> >> > I can probably throw in a few more random reasons, but this should be >> >> > sufficient. >> >> > >> >> > I've offered to add comments, take it or leave it. >> >> >> >> Would you at least agree to use more readable variable names in new >> >> code? That would be of great help to people who will get involved in >> the >> >> Bidi stuff in the future. >> > >> > No. My style is my style. I have a right to use a concise notation as >> much >> > as you have a right to use a verbose notation. The key is that the >> notation >> > be documented. I have agreed to document my notation (when I choose to >> use >> > short names). I'm not complaining about your notation, so please stop >> > complaining about mine. >> > If you would bother to read the Unicode Bidi Algorithm UAX #9 >> > (http://unicode.org/reports/tr9/), you would see a similar short name >> > notation being used. Are you going to suggest UAX #9 must be rewritten >> to >> > use verbose bidi class symbol names? >> > >> >> >> >> Thanks, >> >> Vincent >> > >> > >> > >
