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() :-).


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. # struct Color { float red, green, blue; } # alias Color Colour; # # void setColor (Color x) { ... } # alias setColor setColour; 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. # struct Color { float red, green, blue; } # alias Color Colour; # # void setColor (Color x) { ... } # alias setColor setColour; 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. # struct Color { float red, green, blue; } # alias Color Colour; # # void setColor (Color x) { ... } # alias setColor setColour;

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

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

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

 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

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

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

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

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