>> 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?
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. 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 > >
