Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

A couple of months ago I moved to Germany. Taking some projects on my own, I've recently had the opportunity to develop with a company-based framework, that was very well documented, but in German. My German is pretty good, however my programming terminology is somewhat lacking.

Long story short, I was wondering, how common is it to document code in a language other than English?

Sorry to seem English-centeric but it seems like a bad habit.

share|improve this question
5  
Everything should be written in English cause I know it already. And maybe Japanese cause its cool...and they make Anime. –  P.Brian.Mackey Apr 20 '11 at 20:18
1  
@P.Brian.Mackey it's your lucky day code.google.com/p/nadesiko –  Asaf Apr 20 '11 at 20:33
    
Awesome! –  P.Brian.Mackey Apr 20 '11 at 20:46
    
Depends on how pissed off I am at my boss. –  Satanicpuppy Apr 21 '11 at 13:24
add comment

6 Answers

up vote 3 down vote accepted

Personally, I tend to write all variable/function/class names, comments and documentation in English. And no, it's not my native language (Dutch is).

There are several reasons for this:

  • As others have said, English is the de facto lingua franca of programming. If you're working in an international team (with coworkers, foreign students/teachers, or other contributors to an open source project) it's usually the obvious choice, even if none of the people involved are native speakers.
  • Even for my personal projects that I haven't shared with anyone, I use English. You never know when you might want to distribute something (e.g. by turning it into an open source project, or just sending a copy to a friend).
    • This is especially the case if you might want to distribute the entire revision history by publishing it somewhere, since this way it's more useful without having to go back and translate everything.
    • Even for projects I have no intention of ever sharing with anyone, it's English all the way. Best to keep up the habit.
  • Much of programming and computer jargon is based on English. Even when talking to other native Dutch speakers about these topics, I tend to throw in a lot of English words and phrases. If your comments are going to contain English anyway, they might as well contain only English.
  • Dutch comments often just look wrong somehow. Out of context, maybe.

For non-programming related documentation (e.g. user docs) it really depends on the intended audience. There are definitely cases where providing documentation in non-English languages makes sense, but I think there are very few cases where not providing English documentation makes sense1. Yes, this means you may have to provide the same documentation translated into multiple languages.

1 Even if the product being documented is tightly bound to a geographical region where English is not one of the primary languages, that doesn't necessarily excuse a lack of English docs. For example, tax software for the Dutch market at first look wouldn't seem to need non-Dutch documentation. Until you consider foreigners living and working here, perhaps needing all the help they can get to figure out an unfamiliar tax system. And (western) foreigners living here are much more likely to know English than any other non-Dutch language -- though in this particular example Arabic and Turkish docs might be useful too due to relatively large immigrant communities from those regions.

share|improve this answer
    
Hmm it seems that in the Netherlands it's a little more like in Israel than in Germany, we even tend to communicate in English with one another (in tasks and online, not face2face) –  Asaf Apr 22 '11 at 10:33
add comment

Documentation for programmers or documentation for users?

Anyways, it doesn't matter. Yes in both cases. For users, naturally, in whatever language is required. For programmers, english is lingua franca nowadays, but it still goes.

Why on earth would it be a bad habit? Coming from an english speaking country perhaps? ;) For many (most of the world's population) english is still a foreign language.

share|improve this answer
3  
+1 English is the de facto standard for programming, just like Latin is for medical and legal. –  Rein Henrichs Apr 20 '11 at 20:15
1  
@Rein Henrichs - No. Latin is somewhat more familiar to practicioners of those professions, but is not "de facto standard". They write books, communicate (and everything else) in their own languages, not latin. They certanly don't write books or documentation in latin. –  Rook Apr 20 '11 at 20:18
    
Yes, I am referring to medical terminology, just as English is the de facto standard for programming terminology (language keywords, etc). I am aware that doctors do not write articles in latin. –  Rein Henrichs Apr 20 '11 at 20:21
    
@Rein Henrichs - Just checking :) Btw, language keywords are easily translated (localized) to whatever language. –  Rook Apr 20 '11 at 20:25
    
I'm talking about the developers, and I'm saying it's a bad habit because you have less chance of getting collaboration from other developers in the future... maybe it's just me but don't most developers know english by the fact that they program in that language? –  Asaf Apr 20 '11 at 20:28
show 12 more comments

All aspects of documentation depend on its target audience — including language.

End-user docs should be in the language of the end user: her native tongue, the right terminology, relevant level of detail, etc. For products you sell in other countries you may need to have end-user documentation professionally translated to several languages.

Developer docs can be kept in a language other than English. Non-coders could need to consult it. Coders may have a weak grasp of English, which could make English docs written by them incomprehensible and even incorrect. We did keep internal technical docs in Russian when I worked in Russian teams. This worked well. Nobody had language-related problems, and business terminology blended in well, too.

If your product is built by an international team (commercially or by community), you have to keep your internal documentation in the common language of the industry. Today this is English; in 16th century you'd use Latin. There's virtually no choice.

Our current team speaks mostly Russian, but our documentation and bugtacker is in English, and customers from around the world use it to talk to us and to each other. When I worked in a company staffed with American, Japanese and Russian people, our business requirements were mostly in Japanese and English, most developers spoke Russian, and most operations people spoke Japanese. Of course, we used English for all technical communication and documentation.

share|improve this answer
add comment

I write my documentation in whichever language the customer wants, if I know it. If not, I default to either my own language or English, depending on circumstances (whichever is easier for me and/or the customer to get translated).

Customers deserve nothing less.

share|improve this answer
    
The question is about code documentation. Are you saying, you would document your code in language XYZ, if asked by your customers? Would you also use XYZ for your choice of identifiers for consistency? –  back2dos Apr 21 '11 at 11:36
    
if that were the custom there, of course. At least if I know XYZ well enough to do so. If not, I default to English. –  jwenting Apr 21 '11 at 12:04
    
That is indeed quite noble of you. But I'm not really sure you'd do your customer a favor, because the code will only be maintainable by programmers proficient in XYZ, which IMHO signifficantly diminishes their options in the later phases of the project's life cycle. –  back2dos Apr 21 '11 at 12:27
    
it doesn't, as the customer has a good pool of people available to him. Not every country in the world has English as a major spoken language, even among programmers. Many of my colleagues can barely read enough English to read documentation, let alone write it... –  jwenting Apr 21 '11 at 12:48
add comment

I think it's an awful habit not to write code or documentation in English.

In fact I am German and I profoundly hate code written and documented in German. There is quite a lot of "native" terminology to pick up, which is mingled with English terminology. When you look into the code, you have English framework and library classes/functions/constants along with custom German ones. The result is not only quite ridiculous, but also hard to read, because you have to switch languages in your head all the time.

English is the lingua franca of programming. There's nothing anybody can do about it. And why would you? It's a great thing our community has one. But if you choose not to use it, you lock yourself out from the community. You lock yourself into the decision, that only you and others sufficiently skilled in your language can work with your code.

Native speakers can hardly understand that, because whenever you have a problem, you can just google it. If you google for the same problem in another language, you have a fraction of these results, the best of them giving you a short summary of some information only available in English. This is also why I refuse to use localized software, because I got sick of wasting time trying to translate menu items back and forth to be able to use an English tutorial and a German software together.

Learning English to a degree where you can use it to read and write code and documentation is very easy (at least for native speakers of an Indo-European language). Supposing you daily use 3rd party libraries, which mostly are open source code (unless you're maintaining some business software that was written by dinosaurs), and also take some time to read some of the code and docs, this happens automatically.

And also I think of every language as yet another key to untranslatable wisdoms. So if anybody claims, he has no time to learn English, is probably a sign of short-sightedness, if not even ignorance.

share|improve this answer
add comment

"how common is it to document code in a language other than English?"

In the countries like France which are underdeveloped in everything related to IT and software development in general and especially project management, it happens very frequently.

There are a few large companies which are working with developers from other countries. Those companies have a policy which makes it mandatory to use English everywhere, from the names of files, classes and methods, to the technical (developer oriented) documentation.

Huge number of companies, instead, use French, or a mix of French and bad English (or more often a mix of bad French and bad English). Either they never hire developers outside France, or if they do, bad things happen, since the foreign developers cannot work on the existent codebase.

Do you write Documentation in a language other than English?

Hopefully not. Never. In fact, using languages other than English can cause several problems:

  • By using local language rather than English, you forbid yourself from hiring English-spoken people who don't know the local language. On the opposite, by making English mandatory, you block yourself from hiring developers who don't know English, that is to say the most incompetent ones. And yes, in France, many developers don't know English enough to use online resources like English version of MSDN or StackOverflow.
  • Whenever you work with foreign partners, there might be problems if they need the technical documentation.
  • If you have source code in English (and if not, you have your place in DailyWTF stories) but your documentation is in another language, the following problem arises: would you translate some terms between source code and documentation, or would you mix English and another language in documentation? In the first case, if several people are working on the same project, they may translate terms differently, which will make it very difficult to understand the documentation later.
  • If one day, you'll decide to open source the project, what will happen to the documentation? Would you translate it? Or hide it from the community?
  • It can happen that you decide to sell your software product to another company, including foreign one. If your documentation is in local language, you can't do that (or the price will be much lower, since the product will lack correct, usable documentation).
share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.