www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - US/GB spellings in API design (OT)

reply "John C" <johnch_atms hotmail.com> writes:
What's the consensus for API spelling conventions? Should I use my native 
spelling, British English, or has programming all but standardised on US 
English?

Most APIs seem to use US spellings of words such as 'colour' ('color'), 
'centre' ('center') and 'normalise' ('normalize'). Perhaps it's because the 
well-known ones are written in the US, for example Microsoft's SDK and .NET 
and Sun's JDK. And HTML is US English (align='center'; color='#CCCCCC'). But 
I have used some libraries that have British (or International) English 
spellings - Scintilla springs to mind.

Does it even matter, though? Should I just use whatever comes naturally? 
Which variant do non-English speakers use -- do you write letters, emails 
etc in British English but program in US English? Have I opened a can of 
worms (because Canadian and Australian English, for instance, borrow from 
both)?
Jan 02 2006
next sibling parent =?UTF-8?B?QW5kZXJzIEYgQmrDtnJrbHVuZA==?= <afb algonet.se> writes:
John C wrote:


 Does it even matter, though? Should I just use whatever comes naturally? 


I think US English is in the majority, but I've seen setColour as well.

For bigger projects, it's usually defined in the coding standards etc...


 Which variant do non-English speakers use -- do you write letters, emails 
 etc in British English but program in US English? Have I opened a can of 
 worms (because Canadian and Australian English, for instance, borrow from 
 both)? 


I normally use "pidgin", but maybe I should be using Swedish instead ?

struct färg
{
	float röd,grön,blå;
}

To put that unicode to some use... :-) Seriously, normally US English*.

--anders


* mostly because most of the systems that I use originate from the US ?
Jan 02 2006
prev sibling next sibling parent reply Don Clugston <dac nospam.com.au> writes:
John C wrote:

 What's the consensus for API spelling conventions? Should I use my native 
 spelling, British English, or has programming all but standardised on US 
 English?
 
 Most APIs seem to use US spellings of words such as 'colour' ('color'), 
 'centre' ('center') and 'normalise' ('normalize').  Perhaps it's because the
 well-known ones are written in the US, for example Microsoft's SDK and .NET 
 and Sun's JDK. And HTML is US English (align='center'; color='#CCCCCC'). But 
 I have used some libraries that have British (or International) English 
 spellings - Scintilla springs to mind.
 
 Does it even matter, though? Should I just use whatever comes naturally? 
 Which variant do non-English speakers use -- do you write letters, emails 
 etc in British English but program in US English? Have I opened a can of 
 worms (because Canadian and Australian English, for instance, borrow from 
 both)? 


I don't know about Canada, but in Australia I don't know of many cases 
of US spelling. You'll find lots of cases of "-ize", but actually, most 
of the "-ize" words have always been in the OED as a valid alternative 
spelling of the "-ise" words. So even in British English it is actually 
a choice between two valid spellings.

(BTW, Microsoft Word has very strange ideas about what spelling we use 
in Australia. We all choose "New Zealand" spelling).

"colour"/"color" seems like a very minor issue compared to measurement 
units; it seems absurd to me that Imperial units are allowed anywhere 
near a computer (why are inches included in the Windows GDI, but cubits 
are not? ;-) ). A lot of the APIs you mention have some severe built-in 
US-centricness, eg with date formats, so I don't think they're great 
role models.

Consistency is much more important. Just don't have: 
getColour()/setColor() :-).
Jan 02 2006
parent reply "John C" <johnch_atms hotmail.com> writes:
"Don Clugston" <dac nospam.com.au> wrote in message 
news:dpbgq0$960$1 digitaldaemon.com...

 John C wrote:

 What's the consensus for API spelling conventions? Should I use my native 
 spelling, British English, or has programming all but standardised on US 
 English?

 Most APIs seem to use US spellings of words such as 'colour' ('color'), 
 'centre' ('center') and 'normalise' ('normalize').  Perhaps it's because 
 the
 well-known ones are written in the US, for example Microsoft's SDK and 
 .NET and Sun's JDK. And HTML is US English (align='center'; 
 color='#CCCCCC'). But I have used some libraries that have British (or 
 International) English spellings - Scintilla springs to mind.

 Does it even matter, though? Should I just use whatever comes naturally? 
 Which variant do non-English speakers use -- do you write letters, emails 
 etc in British English but program in US English? Have I opened a can of 
 worms (because Canadian and Australian English, for instance, borrow from 
 both)?


 I don't know about Canada, but in Australia I don't know of many cases of 
 US spelling. You'll find lots of cases of "-ize", but actually, most of 
 the "-ize" words have always been in the OED as a valid alternative 
 spelling of the "-ise" words. So even in British English it is actually a 
 choice between two valid spellings.


True. "-ize" is increasingly common in the UK, depending on taste.


 (BTW, Microsoft Word has very strange ideas about what spelling we use in 
 Australia. We all choose "New Zealand" spelling).


That makes me chuckle, since I grew up in NZ.


 "colour"/"color" seems like a very minor issue compared to measurement 
 units; it seems absurd to me that Imperial units are allowed anywhere near 
 a computer (why are inches included in the Windows GDI, but cubits are 
 not? ;-) ). A lot of the APIs you mention have some severe built-in 
 US-centricness, eg with date formats, so I don't think they're great role 
 models.


Isn't DPI (dots per inch) the standard for printer resolution?


 Consistency is much more important. Just don't have: 
 getColour()/setColor() :-).


Indeed.

What prompted this discussion was a couple of errors I was getting with 
another library, because I was trying to position something with 
CentreToScreen when it wanted CenterToScreen. Took me ages to see what was 
wrong.
Jan 02 2006
parent Oskar Linde <oskar.lindeREM OVEgmail.com> writes:
John C wrote:

 "Don Clugston" <dac nospam.com.au> wrote in message 
 news:dpbgq0$960$1 digitaldaemon.com...
 

"colour"/"color" seems like a very minor issue compared to measurement 
units; it seems absurd to me that Imperial units are allowed anywhere near 
a computer (why are inches included in the Windows GDI, but cubits are 
not? ;-) ). A lot of the APIs you mention have some severe built-in 
US-centricness, eg with date formats, so I don't think they're great role 
models.


 
 Isn't DPI (dots per inch) the standard for printer resolution?


Yes, unfortunately... Your monitor is measured in inches, the engine of 
your car in horse powers, the distance between the pins in many 
connectors are measured in mils, etc... Why are people so reluctant to 
change to something that is obviously better?

Rather irritating are programs that default to Letter instead of A4, and 
where metric units seem to be added as an afterthought... Where the 
usage of metric units leads to rounding errors and subtle bugs. Programs 
that use cm instead of mm and use a default grid-size of 0.127 cm.


Consistency is much more important. Just don't have: 
getColour()/setColor() :-).


 Indeed.


Consistency can still be hard when different libraries use different 
spelling. Using google, some common american spellings are >6 times more 
common than the british ones. A common CS term: "nearest 
neighbor"/"nearest neighbour" has a 4:1 ratio on google and citeseer.
Looking at common function names:

setColor is 60 times more common than setColour
set_color is 130 times more common than set_colour
getCenter is 80 times more common than getCentre

US-english identifiers are problably what most people expect.


 What prompted this discussion was a couple of errors I was getting with 
 another library, because I was trying to position something with 
 CentreToScreen when it wanted CenterToScreen. Took me ages to see what was 
 wrong. 


I once spent ~2 hours in JBuilder staring at semi-autogenerated code 
without noticing that there were two different identifiers: scrollPane1 
and scrollPanel... It didn't help that 1 and l were completely identical 
in the font JBuilder used.

/Oskar
Jan 02 2006
prev sibling next sibling parent John Reimer <terminal.node gmail.com> writes:
John C wrote:

 What's the consensus for API spelling conventions? Should I use my native 
 spelling, British English, or has programming all but standardised on US 
 English?
 
 Most APIs seem to use US spellings of words such as 'colour' ('color'), 
 'centre' ('center') and 'normalise' ('normalize'). Perhaps it's because the 
 well-known ones are written in the US, for example Microsoft's SDK and .NET 
 and Sun's JDK. And HTML is US English (align='center'; color='#CCCCCC'). But 
 I have used some libraries that have British (or International) English 
 spellings - Scintilla springs to mind.
 
 Does it even matter, though? Should I just use whatever comes naturally? 
 Which variant do non-English speakers use -- do you write letters, emails 
 etc in British English but program in US English? Have I opened a can of 
 worms (because Canadian and Australian English, for instance, borrow from 
 both)? 
 
 


Canada, formally, doesn't really borrow from US English.  If we use US 
English, it's just from whim or because we can.  True Canadian English 
uses mostly British spelling. Cheque vs check; centre vs center; metre 
vs meter.  But I have seen more of a drift towards US spelling over the 
years here.  It must be due to the geographical proximity.

On the other hand, most people are such bad spellers, that many wouldn't 
even notice if someone was spelling differently. ;)

-JJR
Jan 02 2006
prev sibling next sibling parent reply Chris Sauls <ibisbasenji gmail.com> writes:
John C wrote:

 What's the consensus for API spelling conventions? Should I use my native 
 spelling, British English, or has programming all but standardised on US 
 English?
 
 Most APIs seem to use US spellings of words such as 'colour' ('color'), 
 'centre' ('center') and 'normalise' ('normalize'). Perhaps it's because the 
 well-known ones are written in the US, for example Microsoft's SDK and .NET 
 and Sun's JDK. And HTML is US English (align='center'; color='#CCCCCC'). But 
 I have used some libraries that have British (or International) English 
 spellings - Scintilla springs to mind.
 
 Does it even matter, though? Should I just use whatever comes naturally? 
 Which variant do non-English speakers use -- do you write letters, emails 
 etc in British English but program in US English? Have I opened a can of 
 worms (because Canadian and Australian English, for instance, borrow from 
 both)? 
 


Personally, I would actually consider using D's 'alias' statements to provide
/both/ options.







I might even start doing this in my own projects, just... because.  And now
that you 
mention it, I'm actually somewhat curious as to just /why/ HTML uses US
spellings, 
considering it was a British advent.

On an unrelated note, anybody else watching the XHTML/2.0 draft?  Its...
interesting.
http://www.w3.org/TR/xhtml2/

-- Chris Sauls
Jan 02 2006
next sibling parent "Unknown W. Brackets" <unknown simplemachines.org> writes:
Yes.  Interesting is a good description.

I'm American, so I shouldn't comment much on this issue, except that 
consistency is what's important.  If my printer says it's 80 dpc (dots 
per centimeter) and I can't find anything in the documentation of 
Photoshop about what the crap that is, I'm going to return the printer, 
and never buy it again, nor recommend it to anyone.

The same goes for documentation.  And toasters for that matter, I want 
American plugs.  I'll return it if it has a British plug.

-[Unknown]



 John C wrote:
 

 What's the consensus for API spelling conventions? Should I use my 
 native spelling, British English, or has programming all but 
 standardised on US English?

 Most APIs seem to use US spellings of words such as 'colour' 
 ('color'), 'centre' ('center') and 'normalise' ('normalize'). Perhaps 
 it's because the well-known ones are written in the US, for example 
 Microsoft's SDK and .NET and Sun's JDK. And HTML is US English 
 (align='center'; color='#CCCCCC'). But I have used some libraries that 
 have British (or International) English spellings - Scintilla springs 
 to mind.

 Does it even matter, though? Should I just use whatever comes 
 naturally? Which variant do non-English speakers use -- do you write 
 letters, emails etc in British English but program in US English? Have 
 I opened a can of worms (because Canadian and Australian English, for 
 instance, borrow from both)?


 
 
 Personally, I would actually consider using D's 'alias' statements to 
 provide /both/ options.
 





 
 I might even start doing this in my own projects, just... because.  And 
 now that you mention it, I'm actually somewhat curious as to just /why/ 
 HTML uses US spellings, considering it was a British advent.
 
 On an unrelated note, anybody else watching the XHTML/2.0 draft?  Its... 
 interesting.
 http://www.w3.org/TR/xhtml2/
 
 -- Chris Sauls
Jan 02 2006
prev sibling parent "John C" <johnch_atms hotmail.com> writes:
"Chris Sauls" <ibisbasenji gmail.com> wrote in message 
news:dpbsgp$1836$1 digitaldaemon.com...

 John C wrote:

 What's the consensus for API spelling conventions? Should I use my native 
 spelling, British English, or has programming all but standardised on US 
 English?

 Most APIs seem to use US spellings of words such as 'colour' ('color'), 
 'centre' ('center') and 'normalise' ('normalize'). Perhaps it's because 
 the well-known ones are written in the US, for example Microsoft's SDK 
 and .NET and Sun's JDK. And HTML is US English (align='center'; 
 color='#CCCCCC'). But I have used some libraries that have British (or 
 International) English spellings - Scintilla springs to mind.

 Does it even matter, though? Should I just use whatever comes naturally? 
 Which variant do non-English speakers use -- do you write letters, emails 
 etc in British English but program in US English? Have I opened a can of 
 worms (because Canadian and Australian English, for instance, borrow from 
 both)?


 Personally, I would actually consider using D's 'alias' statements to 
 provide /both/ options.








That's a nice solution. Thanks for the suggestion, I'll use it.


 I might even start doing this in my own projects, just... because.  And 
 now that you mention it, I'm actually somewhat curious as to just /why/ 
 HTML uses US spellings, considering it was a British advent.


I've gleaned that Berners-Lee handed development of HTML over to the 
Internet Engineering Task Force, who were US-based. As well as that, 
Netscape and Microsoft added proprietry extensions, some of which were later 
adopted as standard. So it's a bit of a mish-mash.


 On an unrelated note, anybody else watching the XHTML/2.0 draft?  Its... 
 interesting.
 http://www.w3.org/TR/xhtml2/

 -- Chris Sauls
Jan 02 2006
prev sibling next sibling parent reply S. Chancellor<dnewsgr mephit.kicks-ass.org> writes:
"John C" <johnch_atms hotmail.com> wrote:

What's the consensus for API spelling conventions? Should I use my native 
spelling, British English, or has programming all but standardised on US 
English?

Most APIs seem to use US spellings of words such as 'colour' ('color'), 
'centre' ('center') and 'normalise' ('normalize'). Perhaps it's because the 
well-known ones are written in the US, for example Microsoft's SDK and .NET 
and Sun's JDK. And HTML is US English (align='center'; color='#CCCCCC'). But 
I have used some libraries that have British (or International) English 
spellings - Scintilla springs to mind.

Does it even matter, though? Should I just use whatever comes naturally? 
Which variant do non-English speakers use -- do you write letters, emails 
etc in British English but program in US English? Have I opened a can of 
worms (because Canadian and Australian English, for instance, borrow from 
both)? 


Since D has aliases, why don't you do both?  Then we don't have to go
looking through the documentation when Object.Color is missing :)
-- 
Email works.
Jan 02 2006
parent reply "John C" <johnch_atms hotmail.com> writes:
"S. Chancellor" <dnewsgr mephit.kicks-ass.org> wrote in message 
news:dpc3bq$1ru5$1 digitaldaemon.com...

 "John C" <johnch_atms hotmail.com> wrote:

What's the consensus for API spelling conventions? Should I use my native
spelling, British English, or has programming all but standardised on US
English?

Most APIs seem to use US spellings of words such as 'colour' ('color'),
'centre' ('center') and 'normalise' ('normalize'). Perhaps it's because 
the
well-known ones are written in the US, for example Microsoft's SDK and 
.NET
and Sun's JDK. And HTML is US English (align='center'; color='#CCCCCC'). 
But
I have used some libraries that have British (or International) English
spellings - Scintilla springs to mind.

Does it even matter, though? Should I just use whatever comes naturally?
Which variant do non-English speakers use -- do you write letters, emails
etc in British English but program in US English? Have I opened a can of
worms (because Canadian and Australian English, for instance, borrow from
both)?


 Since D has aliases, why don't you do both?  Then we don't have to go
 looking through the documentation when Object.Color is missing :)


I've been playing around with aliasing symbols, but it's not possible to 
override an alias for a class method, so this approach would lead to 
inconsistency.

struct Color { ... }
alias Color Colour;

class ColorPicker {

    private Color color_;

    Color color() { return color_; }
    void color(Color value) {
        color_ = value;
        onColorChanged();
    }
    alias color colour;

    protected void onColorChanged() { ... }
    alias onColorChanged onColourChanged;

}
alias ColorPicker ColourPicker;

class MyColourPicker : ColourPicker {

    protected override void onColourChanged() { ... }

}

Produces error: function MyColourPicker.onColourChanged function 
onColourChanged does not override any.
Jan 03 2006
parent Chris Sauls <ibisbasenji gmail.com> writes:
John C wrote:

 "S. Chancellor" <dnewsgr mephit.kicks-ass.org> wrote in message 
 news:dpc3bq$1ru5$1 digitaldaemon.com...
 

"John C" <johnch_atms hotmail.com> wrote:


What's the consensus for API spelling conventions? Should I use my native
spelling, British English, or has programming all but standardised on US
English?

Most APIs seem to use US spellings of words such as 'colour' ('color'),
'centre' ('center') and 'normalise' ('normalize'). Perhaps it's because 
the
well-known ones are written in the US, for example Microsoft's SDK and 
.NET
and Sun's JDK. And HTML is US English (align='center'; color='#CCCCCC'). 
But
I have used some libraries that have British (or International) English
spellings - Scintilla springs to mind.

Does it even matter, though? Should I just use whatever comes naturally?
Which variant do non-English speakers use -- do you write letters, emails
etc in British English but program in US English? Have I opened a can of
worms (because Canadian and Australian English, for instance, borrow from
both)?


Since D has aliases, why don't you do both?  Then we don't have to go
looking through the documentation when Object.Color is missing :)


 
 
 I've been playing around with aliasing symbols, but it's not possible to 
 override an alias for a class method, so this approach would lead to 
 inconsistency.
 
 struct Color { ... }
 alias Color Colour;
 
 class ColorPicker {
 
     private Color color_;
 
     Color color() { return color_; }
     void color(Color value) {
         color_ = value;
         onColorChanged();
     }
     alias color colour;
 
     protected void onColorChanged() { ... }
     alias onColorChanged onColourChanged;
 
 }
 alias ColorPicker ColourPicker;
 
 class MyColourPicker : ColourPicker {
 
     protected override void onColourChanged() { ... }
 
 }
 
 Produces error: function MyColourPicker.onColourChanged function 
 onColourChanged does not override any. 
 
 


Smells like a bug to me.  Unless, of course, the 'alias' is not supposed to be
inherited, 
which wouldn't quite seem right to me.  I know Mango uses method aliasing A
LOT, might go 
compare code...  (I haven't read much of the Mango source for a while.)

-- Chris Sauls
Jan 03 2006
prev sibling next sibling parent reply "Matthew" <matthew hat.stlsoft.dot.org> writes:
"John C" <johnch_atms hotmail.com> wrote in message
news:dpb4si$2aoj$1 digitaldaemon.com...

 What's the consensus for API spelling conventions? Should I use my native
 spelling, British English, or has programming all but standardised on US
 English?

 Most APIs seem to use US spellings of words such as 'colour' ('color'),
 'centre' ('center') and 'normalise' ('normalize'). Perhaps it's because


the

 well-known ones are written in the US, for example Microsoft's SDK and


.NET

 and Sun's JDK. And HTML is US English (align='center'; color='#CCCCCC').


But

 I have used some libraries that have British (or International) English
 spellings - Scintilla springs to mind.

 Does it even matter, though? Should I just use whatever comes naturally?
 Which variant do non-English speakers use -- do you write letters, emails
 etc in British English but program in US English? Have I opened a can of
 worms (because Canadian and Australian English, for instance, borrow from
 both)?


Strategies:

    1. chose neutral where possible
    2. Use contractions where appropriate - e.g. one can avoid
initialise/initialize with init. But contractions are generally frowned on
in public interface
    3. Use typedefs / alias
    4. Use overloads, when they do not risk screw ups
    5. Stubbornly do what is native to you

And, when all else fails, thought it gauls me to say so, the best strategy
is probably ... no, I can't say it! ... er ... howl .... to use US English
spelling. :-(
Jan 02 2006
parent "John C" <johnch_atms hotmail.com> writes:
"Matthew" <matthew hat.stlsoft.dot.org> wrote in message 
news:dpcf3l$2qq3$1 digitaldaemon.com...

 "John C" <johnch_atms hotmail.com> wrote in message
 news:dpb4si$2aoj$1 digitaldaemon.com...

 What's the consensus for API spelling conventions? Should I use my native
 spelling, British English, or has programming all but standardised on US
 English?

 Most APIs seem to use US spellings of words such as 'colour' ('color'),
 'centre' ('center') and 'normalise' ('normalize'). Perhaps it's because


 the

 well-known ones are written in the US, for example Microsoft's SDK and


 .NET

 and Sun's JDK. And HTML is US English (align='center'; color='#CCCCCC').


 But

 I have used some libraries that have British (or International) English
 spellings - Scintilla springs to mind.

 Does it even matter, though? Should I just use whatever comes naturally?
 Which variant do non-English speakers use -- do you write letters, emails
 etc in British English but program in US English? Have I opened a can of
 worms (because Canadian and Australian English, for instance, borrow from
 both)?


 Strategies:

    1. chose neutral where possible


Yip. I've also considered using synonyms for concepts like 'colour', but 
hue, chroma, shade, cast and tint etc have different meanings in computing 
terms (especially in graphics apps). And pigment, tinge and tinct are just 
too purple, as it were.


    2. Use contractions where appropriate - e.g. one can avoid
 initialise/initialize with init. But contractions are generally frowned on
 in public interface


And there's a horrific trend in some languages where vowels are removed from 
words to make function names shorter.


    3. Use typedefs / alias


Looked like a nice solution, until I discovered aliases for functions can't 
be used to override the original.


    4. Use overloads, when they do not risk screw ups


Might lead to inconsistency when overloads can't be used.


    5. Stubbornly do what is native to you


I wouldn't think of changing my spelling in an article just to make it 
easier for my US friends to read. I guess code is a different matter.


 And, when all else fails, thought it gauls me to say so, the best strategy
 is probably ... no, I can't say it! ... er ... howl .... to use US English
 spelling. :-(


That's the conclusion I've reached, too. It's not a big deal, but it was a 
fun investigation.
Jan 03 2006
prev sibling next sibling parent Manfred Nowak <svv1999 hotmail.com> writes:
John C wrote:

[...]

 Which variant do non-English speakers use


[...]

English teached in schools tolerates mixed usage.

In programming tolerance increases towards wrong spellings, like 
"putted".

-manfred
Jan 03 2006
prev sibling parent Bruno Medeiros <I.AM FAIAL.com> writes:
John C wrote:

 What's the consensus for API spelling conventions? Should I use my native 
 spelling, British English, or has programming all but standardised on US 
 English?
 
 Most APIs seem to use US spellings of words such as 'colour' ('color'), 
 'centre' ('center') and 'normalise' ('normalize'). Perhaps it's because the 
 well-known ones are written in the US, for example Microsoft's SDK and .NET 
 and Sun's JDK. And HTML is US English (align='center'; color='#CCCCCC'). But 
 I have used some libraries that have British (or International) English 
 spellings - Scintilla springs to mind.
 
 Does it even matter, though? Should I just use whatever comes naturally? 
 Which variant do non-English speakers use -- do you write letters, emails 
 etc in British English but program in US English? Have I opened a can of 
 worms (because Canadian and Australian English, for instance, borrow from 
 both)? 
 
 


American English here. It's the more common one, and also in some cases 
a bit more uniform/direct . For instance, 'center' is written much more 
like the way it sounds, 'centre' on the hand looks French to me :)
Jan 02 2006