Chronological Thread 

< Chronological >      < Thread >

---

Randall Britten wrote:
> Hi all
>
> Good points, but my feeling is that the current trend on our project is to
> overuse abbreviations. My preference would be to make it standard practice
> to avoid abbreviations, and only use them in special cases.
>
I don't like the idea of having hard-and-fast rules for things like this
- part of the process to having readable code is to not follow any rules
too religiously but instead use discretion to write code that is
readable. As soon as you follow a particular rule even when it doesn't
make sense, you end up with all sorts of quirks which actually makes
things worse. For an example of this, try reading a COBOL program (or to
a lesser extent, the earlier versions of FORTRAN) - COBOL imposes many
constraints on formatting, and the result is programs which are harder
to read.

> If non-abbreviated identifiers make the code hard to read because the lines
> are longer, or the "generic-ness" seems lost, using abbreviations is
> probably not the best way of improving the code's readability. There are
> heaps of refactoring techniques out there that allow for readable code
> without having to resort to abbreviations.
>
Refactoring code generally involves making things more generic, which is
exactly when you have to resort to abbreviations. For example, your
index might have changed from "currentRowIndexIntoTheTransitionMatrix" to i.

There will often be more than one way to improve readability, but that
doesn't mean we should leave common sense in terms of what is the most
readable behind on any one aspect of writing readable code.

Often, i is the most sensible character to use for a loop index, and the
meaning of i is usually right there because i is not in scope for very
long. It is also convention, so doing something else will probably just
confuse people.

Another example of a code use of abbreviations is when referring to
something that is usually abbreviated. For example, it wouldn't make
sense for a CVODE instance to be referred to by the full expansion of
CVODE (I don't even know what that is without looking it up, and if I
saw it, I would probably not recognise it as CVODE).

Best regards,
Andrew

> Regards,
> Randall
>
>
>> -----Original Message-----
>> From: cellml-tools-developers-bounces at cellml.org [mailto:cellml-tools-
>> developers-bounces at cellml.org] On Behalf Of Andrew Miller
>> Sent: Thursday, 1 November 2007 10:38 a.m.
>> To: A list for the developers of CellML tools
>> Subject: Re: [cellml-dev] Code style suggestion
>>
>> Randal Britten wrote:
>>
>>> Hi all
>>>
>>> I would like to suggest that we change our current code style
>>> standard. I think that abbreviations should be avoided for
>>>
>> identifier
>>
>>> names. Abbreviations remained popular because they saved some typing,
>>> but modern IDE's have autocompletion and similar features.
>>>
>>> Not sure if Emacs supports autocompletion or not. I know this will
>>>
>> be
>>
>>> harder if Emacs does not support autocompletion,
>>>
>> emacs has had a feature called dabbrev (dynamic abbreviations) since
>> 1991, which is roughly equivalent to what other editors have later
>> called autocompletion.
>>
>>> but I don't think we
>>> should compromise our coding style for the sake of a particular
>>>
>> editor.
>>
>> I don't think that we should automatically assume that it is bad coding
>> style to use abbreviations. I think that this sort of decision should
>> be
>> made on a case-by-case basis.
>>
>> Brevity of code is always going to be a trade-off - very long code is
>> hard to read because:
>> 1) you end up with long, hard to read, lines, or wrap a small amount
>> of actual code over a large number of lines, again making it hard
>> to read.
>> 2) it becomes harder to focus on the algorithm because of all the
>> unnecessary details (the whole point of mathematics is to hide the
>> details of the problem and solve the problem in the abstract, and
>> similar concerns often transfer well to code).
>>
>> However, overly succinct code can also be hard to read.
>>
>> I think that things like using traditional variable names like i and j
>> for loop indices is sensible and improves readability, and often also
>> makes the code more abstract and re-usable (of course, such variables
>> should ideally be short-lived local variables).
>>
>> Longer lived variables (globals, class members etc...) benefit more
>> from
>> having a more verbose name. Reasonable (unambiguous) abbreviations are
>> not a problem, especially if the abbreviation is already common outside
>> the code (for example, I find 'spec' easier to read in the graph code
>> than 'specification' would be, and it is reasonably clear in the
>> context
>> what an object called spec stores).
>>
>> Best regards,
>> Andrew
>>
>>
>>> Regards,
>>> Randall
>>>
>>>
>>> ----------------------------------------------------------------
>>> This message was sent using IMP, the Internet Messaging Program.
>>>
>>> _______________________________________________
>>> cellml-tools-developers mailing list
>>> cellml-tools-developers at cellml.org
>>> http://www.cellml.org/mailman/listinfo/cellml-tools-developers
>>>
>>>
>> _______________________________________________
>> cellml-tools-developers mailing list
>> cellml-tools-developers at cellml.org
>> http://www.cellml.org/mailman/listinfo/cellml-tools-developers
>>
>
> _______________________________________________
> cellml-tools-developers mailing list
> cellml-tools-developers at cellml.org
> http://www.cellml.org/mailman/listinfo/cellml-tools-developers
>

---

• [cellml-dev] Code style suggestion, Andrew Miller, 11/01/2007
  • [cellml-dev] Code style suggestion, Randall Britten, 11/01/2007
    • [cellml-dev] Code style suggestion, Andrew Miller, 11/01/2007
      • [cellml-dev] Code style suggestion, Randall Britten, 11/01/2007
        • [cellml-dev] Code style suggestion, Justin Marsh, 11/01/2007

---

Archive powered by MHonArc 2.6.18.