Embedded programming usually solo? - Page 2

Do you have a question? Post it now! No Registration Necessary

Translate This Thread From English to

Threaded View
Re: Embedded programming usually solo?
Quoted text here. Click to load it
<snip>

It's been my experience that the quality of documentation is more heavily
related to the philosophy of the company itself, and not the size of the
team. Companies which tend to follow a more rigorous set of guidelines tend
to have better documentation. These are the companies which might still have
a QC guy with a little round rubber stamp. He could/would prevent products
from shipping if documentation was lacking.

Many (most) modern companies are so consumed with bottom-lines, that they
just want to get products "out the door." Documentation can be a tedious and
time consuming process, especially when the most talented engineers (with
the best knowledge of the product) are generally not used as technical
writers. They move on to other projects, so they can get more new products
"out the door." IMHO, that is why documentation suffers.

Regards,
Tom




Re: Embedded programming usually solo?

Quoted text here. Click to load it

It is extremely difficult to describe anyone else's thought processes.
When I look at a schematic diagram or a piece of program created by
someone else (or me years earlier), there are always strange things
I do not understand. Why was that done that way when a much simpler
way exists? Quite often there is a good answer, because of this and
that. This small piece of information may turn out to be very important
in case there are problems later on.

So, the documentation has to be written by the same people who have
gone through the thought process. Preferably during or immediately
after the thinking.

- Ville

--
Ville Voipio, Dr.Tech., M.Sc. (EE)

Re: Embedded programming usually solo?
Quoted text here. Click to load it
... snip ...
Quoted text here. Click to load it

IMO most of what you describe should be notes or comments in the
master drawings or sources.  It does not belong in what I consider
to be 'user documentation', and probably should never be separated
into easily lost or ill-maintained separate verbiage.

--
Chuck F ( snipped-for-privacy@yahoo.com) ( snipped-for-privacy@worldnet.att.net)
   Available for consulting/temporary embedded and systems.
We've slightly trimmed the long signature. Click to see the full one.
Re: Embedded programming usually solo?

Quoted text here. Click to load it

I am a hw guy, most of the time. I always try to make a
few papers about each circuit, as I tend to forget things
even myself. In sw a lot can (and must) be done in the source
comments. However, I still feel there is a need for some
documentation outside of that, especially in larger projects.
What is behind this module division? Why were the sw interfaces
chosen as they are?

User documentation is an entirely different story. It requires
a lot of non-technical skills, as well. I think the user
documentation should be written by technically skilled
writers who have not been writing code or designing hw in
the project. That gives them a more customer-like attitude.
(Not marketing, not the hw/sw designers.)

"Why did you do it this way? There is no way to
explain this clearly in the manual!" "Umm, it's crystal clear,
it took me only seven fortnights to figure it out."

And, of course, this depends on your customers. If
you sell pieces of software to other programmers, you can
use very technical descriptions. If you are selling real things
to end-users, they cannot be expected to be specialists on
your field.

- Ville

--
Ville Voipio, Dr.Tech., M.Sc. (EE)

Re: Embedded programming usually solo?

[...]
Quoted text here. Click to load it

Heck, it's often difficult to remember (let alone describe) my own
thought processes when looking at code I'd written six months earlier.
The process:

 - "What was I thinking?"
 - [edit, compile link, test, <SNAP> (sound of code breaking)]
 - "Oh yeah..."

;-)

Regards,

                               -=Dave
--
Change is inevitable, progress is not.

Re: Embedded programming usually solo?

Quoted text here. Click to load it

I had a guy working for me who used to crank out hundreds of lines of code
- in a day or two - without a single comment. When I challenged him on this
he would respond: "but my coding style is so obvious it's practically self
commenting..."
I should have put him to death of course, but he was just so damned
brilliant.


Bob

Re: Embedded programming usually solo?
Quoted text here. Click to load it

In principle, of course, code is self documenting.  After all, the
computer has no problem in reading it, understanding it, and doing
exactly what the code tells it to do!  It's just our undertanding
of the programming language is not as good as the computer's, so we
need all the extra verbiage around the code to try to explain what
the code means.  If we spoke native C or whatever there'd be no issue!

Does anyone produce compilers where the language keywords are in
languages other than English?

    pour (i = 0; i < 10; i++)
    {
        ecritf("%d", i);
    }
    sortie(0)

I've come across code in which variable names and comments were in
French and the C in English, which just looks silly ;-)

--
Trevor Barton

Re: Embedded programming usually solo?

Quoted text here. Click to load it
I began programming in Assembler - machine language actually now that I
think about it, and I was taught by my boss at that time to comment my code
such that a non-programmer could scan through it and get the gist of what I
was up to. I still think that is a good underlying premise for documenting
code.

Bob




Quoted text here. Click to load it
         ecritf("%d", i);    //LOL ;)
Quoted text here. Click to load it

I18n of programming languages (was: Re: Embedded programming usually solo?)

Quoted text here. Click to load it


I strongly hope that nobody ever did anything as braindead as that for
the embedded market.  People in this field should definitely know
better.  And of course, for C programs, you could always do that
yourself using the preprocessor, if you really want to.  But honestly
I think nobody ever should unless they're writing a submission for the
IOCCC.

But there _have_, of course ;-(, been attempts in that direction.
E.g. Microsoft "WordBasic", the internal scripting language of WinWord
6.0, had the entire standard library available in the products
installation language --- whereas they at least had the decency to let
the language keywoards alone, IIRC.

That obviously caused a major maintenance desaster when they saw the
error of their ways only one release further down the road (VBA, as of
Word 97), and everything had to be translated _twice_: first from
internationalized Word Basic to English Word Basic, then from there to
VBA.

--
Hans-Bernhard Broeker ( snipped-for-privacy@physik.rwth-aachen.de)
Even if all the snow were burnt, ashes would remain.

Re: Embedded programming usually solo?
Quoted text here. Click to load it
... snip ...
Quoted text here. Click to load it

It has happened, but is a bad idea.  The result is totally
non-portable, and certainly non-understandable by a non French
reading (in the above case) maintainer.  Most reasonably
intelligent programmers are quite capable of memorizing a 30 to 60
word furrin vocabulary.

--
Chuck F ( snipped-for-privacy@yahoo.com) ( snipped-for-privacy@worldnet.att.net)
   Available for consulting/temporary embedded and systems.
We've slightly trimmed the long signature. Click to see the full one.
Re: Embedded programming usually solo?

Quoted text here. Click to load it

It may... if your native language is English. For most of us, it is not.
We silly forigners who bad English speek, find may more easier commenting
in our own tongue.

The choice of comment language not an obvious one. There are
several factors which should be taken into account:

- which language does the programmer master best:
   almost all people have a language which they master better
   than any other language. Using this language generally produces
   more fluent text.

- who is going to read the comment:
   if the comments are strictly for internal use, they can be
   written in the same language as all internal memos, etc.
   If the comments are part of the user documentation, then
   the language of the user documentation dictates the choice.

- which language can be written:
   languages using non-latin alphabets may require severe
   translitteration abuse before they can be embedded into
   source code

So, sometimes, it is not completely stupid to use non-English
variables and comments.

What comes to the language of the programming language itself,
it does not really matter. Learning some dozens of nonsense codewords
should not be a problem for anyone, be it printf(), écritf(),
skrivf(), kirjoitaf(), schreibef() or whatever. (Even though my
English vocabulary was a bit odd in the beginning, as I spoke
Basic before English :)

- Ville

--
Ville Voipio, Dr.Tech., M.Sc. (EE)

Re: Embedded programming usually solo?
Quoted text here. Click to load it

Oh, I hope noone thought I was being Englishist in my comment.
Commenting code in the native language of the users (code users
rather than end users) is the only sensible thing to do.  I only
meant that the mix of two languages in one "document" looks a
bit odd!

Quoted text here. Click to load it

Yes, I agree entirely.

Quoted text here. Click to load it

Sorry, I don't know how to get an acute accent over an "e" on
my keyboard, that's why I used ecritf().  Anyway, I also don't
know the french for "format", which is why I left the "f" alone,
although I'd hesitate a guess it's "format"??

--
Trevor Barton

Re: Embedded programming usually solo?
Quoted text here. Click to load it

Funny. I am Dutch, but I always comment my code in English. When I'm
programming, my mind seems to be set to English because the programming
language or asm mnemonics are all English. Even when I write a manual for a
new product, the first version is in English and the Dutch version a
translation of the first....

Meindert



Re: Embedded programming usually solo?

Quoted text here. Click to load it
a


So do I. Commenting in Finnish will have problems with characters missing in
the English character set. The same applies for variable names in languages
other than English.

If the code will ever be destined for international use, English is
practically the only sensible option (sorry, mes amis en France, the time of
French as an international universal language is over - it time was 100
yeras ago).

Tauno Voipio
tauno voipio @ iki fi



Re: Embedded programming usually solo?
Quoted text here. Click to load it
in
languages

This brings back a memory from over 20 years ago. I had to find a bug in
some software written in PL/M, running on a PDP-11. It controlled a Nokia
machine and the software was commented in ..... Finnish. Brr, what a
horrible language ;-)

Meindert



Re: Embedded programming usually solo?

Quoted text here. Click to load it

The official internal language in Nokia is English, which was sort of
a surprise to me at first.  But the attitude tends to be "no one is
ever going to bother learning our language, so we'll happily learn
theirs", which just goes to show how far away Finland is from France.
So of course, the code is all commented in English for the most part.

--
Darin Johnson
    "Floyd here now!"

Re: Embedded programming usually solo?
Quoted text here. Click to load it

Well, I was referring to some code from over 20 years ago. They probably
changed the policy.

Meindert



Re: Embedded programming usually solo?

Quoted text here. Click to load it

At least I did not. And I have to admit I do comment my code in
English, even when noone else is going to see the code. And I don't
have anything against English as the "Lingua Franca" in technology.
English does not suffer from any extremely complicated grammar,
and getting started is simple. It is also socially acceptable
to speak bad English...

I just wanted to point out there are situations where commenting
in something else than English may be justified.

Quoted text here. Click to load it

I do agree. When I first saw a local programming coursebook, I
thought it looked extremely funny. All variables, all comments
were in Finnish.

However, there seems to be some sort of "maximum difficulty constant"
in education: the sum of lingual difficulties and topical difficulties
must not exceed some certain constant. So, if the topic is difficult,
the language must be as easy. Programming is difficult at first,
so the language must be the students' native language (if possible).

But, yes, the world would be much simpler place if we all spoke
the same language :)

- Ville

--
Ville Voipio, Dr.Tech., M.Sc. (EE)

Re: Embedded programming usually solo?
Quoted text here. Click to load it
... snip ...
Quoted text here. Click to load it

Not if you are incapable of making your basic wants known in some
other language :-)
Quoted text here. Click to load it

This sub-thread began when somebody was proposing translating key
words, rather than comments.  The actual discussion makes more
sense than that.

--
Chuck F ( snipped-for-privacy@yahoo.com) ( snipped-for-privacy@worldnet.att.net)
   Available for consulting/temporary embedded and systems.
We've slightly trimmed the long signature. Click to see the full one.
Re: Embedded programming usually solo?

Quoted text here. Click to load it

Pointing and grunting works pretty well in most parts.

- Ville

--
Ville Voipio, Dr.Tech., M.Sc. (EE)

Site Timeline