> There were two general objections. The first is that English is an
> imprecise language that is easily abused. It's pretty easy to write
> sentences that are redundant, recursive, vague and open to multiple
> interpretations. I agree!

I do too. English, like all non-formal languages, is imprecise.  All human languages are imprecise because they are constantly evolving.  Actually, the PERL programming language is also imprecise.  When I was learning it, I stumbled in the manual on a consolation: "PERL will do the right thing most of the time."
We deal with that imprecision by removing all extraneous verbiage, and if we make ambiguous statements, they are qualified by the context.  In general, that is.  As has been stated in the Muse many times, the very existence of comments is controversial.

> The second objection was that English is far from a universal
> language. Wikipedia pegs the number of languages used in the world at
> as many as 7000. Should a Farsi speaker be required to document in
> English, which may be a very foreign lingo?

The objection is fallacious.  If the engineering is done in Iran, then, by all means, use Farsi as a commenting language.  But if the work is done in an English-speaking environment, then comments *must* be in English.  It may be bad English, and it might need to be corrected during the code review, but it must be English.  I did have to deal with comments like "start fire manger," and we fixed that with some laughs.  The process needs to be agreed upon.  Unfortunately, it seldom even exists, and corrections are not made because "who reads the comments anyway?" and for the fear of insulting the author.  I see it as just wrong.  It's better to strip bad comments altogether than to leave useless crap in the source.

I'm not really sympathetic to the general objections posed to documentation, because all of the objections can be stated equally with regard to source code. For example:

• "C is an imprecise language that can be easily abused" (and often is), yet we are still here writing code in C. So why is it that an imprecise language that can be easily abused is good enough for writing the code, but one that provides more precision than the programming language is not suitable for documenting it? There are many more words in the English language than the "C" vocabulary provides, leading to a larger degree of possible precision. Whether or not someone is using a language precisely is a different factor to consider, and not the fault of the language itself.
• "C is far from a universal language", yet we can write programs in it. So why is it ok for us to write programs in C, when it is far from universal?

And, I'm by no means an English maximalist (who cares? document in whatever language you want, as long as it meets the needs of your future team and customers).

> <https://www.ganssle.com/tem/tem449.html#quotesandthoughts> was "If you
> can't write it down in English, you can't code it." Not everyone agreed.
>
> There were two general objections. The first is that English is an
> imprecise language that is easily abused. It's pretty easy to write
> sentences that are redundant, recursive, vague and open to multiple
> interpretations.

That also sounds very much like C, isn't it ? Yet there is no excuse to properly express ourselves in C, because neither the compiler nor the processor will make any efforts to try to understand the actual meaning of what we are writing.

> The second objection was that English is far from a universal language.
> Wikipedia <https://en.wikipedia.org/wiki/Language> pegs the number of
> languages used in the world at as many as 7000. Should a Farsi speaker
> be required to document in English, which may be a very foreign lingo?

I don't know how many programming languages there are, but if we expect the technological equivalent of "someone to talk to" we'll use a common enough language in order to get decent programmers, a decent compiler, a decent optimizer, at least.

Hence, the same applies to the comments language...

Imagine if the first scientific books would have been written in any local language... Latin was the common language for that and any respectable science practitioner would learn Latin. Same for English these days.

I don't imagine learning French to grasp Fourier series, then Danish to understand the Doppler effect, then Italian for the relativity principle, then German for the general relativity theory, and so on...

Well, English is now the common language and hence comments should be written in English unless you are willing to be limited by the reach of your language (like in your Czech example, great btw)

I have slightly conflicted views on it.

Your choice of programming language should be the most precise and concise language to documentation of how it works.

Your unit tests are the most accurate and reliable documentation of what it does. (So design them so it is readable as such)

You only need the English for the "why" your code is that way or does this.

On the other extreme, like the sign at the top of the proverbial ladder,  "Start Other Side".

I wish we would _start_ with the sales brochure and user documentation.

If you can't explain simply and clearly to a user what the value of the feature is, what it does and how to use it.... it's not going to be valued, it's not going to sell, it is not going to be used, and it's going to be hell to build and test, and is going to be buggy because nobody is quite sure what it is meant to do.

And if you can't do any of that, go away and build something you can.

Apropos to commenting code in English, the language of international aviation is English. At a large airport in France, for example, controllers are supposed to speak ONLY English, even when talking to pilots who are native French speakers. The fact that this convention is not always observed has led to several near disasters, such as almost landing on top of another airplane!

A professional pilot addresses this issue in his video at https://www.youtube.com/watch?v=_WkxkrtrFsg&t=20s.

From January 1985 to October 1989 I was technical publications manager (and first writer, starting the department) or lead writer and team lead for our operating system documentation at BiiN, the Intel/Siemens joint venture to build a new hardware, software, and systems architecture that was performant, high-security, fault tolerant, concurrent, and object-oriented in the hardware. Our capability-based operating system was written entirely in Ada and the operating system documentation was perhaps a third of the 57 manuals and 15,000 pages of documentation the writers produced.

Early on I struck a bargain with the operating system managers, that the writers owned the comments in the OS package specifications' source code and the developers owned the code. We created tools to verify that writers did not accidentally change the code and tools to generate the OS manuals directly from the comments, an early form of single-sourcing multiple documentation formats. Our OS API reference manual was about 3,000 pages spread across multiple printed volumes and generated automatically. Ruthless editing plus readability scoring tools meant that our OS documentation could be used by an eighth grader, if the eighth grader was a systems programmer fluent in Ada.

I mention all this to recommend the same approach today. Let the writers own the interface comments and the programmers own the rest of the code, regardless of which tools are being used to turn comments into documentation. A good technical writer can document your interfaces better than most developers can.

(And I'm not job-hunting with these comments, as I work full-time for a Laramie startup as a senior software engineer.)

I finally had time to obtain a copy of this book which you reviewed a while ago, and have a good look at it. I have a few comments I'd like to pass on.

I learned quite a bit from the book, particularly on the subject of verifying timing when an RTOS is involved, and the existence of static analysis tools for doing so.

However, I was quite surprised to see an almost complete absence of discussion of bare metal systems using a co-operative scheduler. For me this has been a "goto" approach for hard real-time control which I have found to be very reliable over several projects.

Gliwa does discuss bare-metal applications briefly on pages 38-40, presenting two applications which are in my opinion a bit naive in their simplicity. He then goes on to say (p40):

"Experience shows that such approaches are expanded over time ... (until) ... configuration and implementation are wildly mixed. In such cases the development team has failed to make a timely switch to the use of an operating system."

The rest of the book then goes on to discuss ways of validating system timing when an RTOS is used, which is not simple, given the complexities of configuring task priorities, allowing for timing variations due to context switching, and also the use of cache and pipelines on top of that.

It seems to me that the author has not at all done justice to the possibilities of a cooperative scheduler on bare metal. A few years ago I implemented (on a 32 bit PIC) such a system which accepted and responded to serial commands via UART, simultaneously activated and controlled 3 stepper motors (with a constant acceleration profile to get to minimise forces on the load), while also reading a laser sensor, using averaged readings from which to find edges of objects in the path and report them back. All of this was achieved without an RTOS and has been extremely stable over several years of daily use. (In fact so solid that I would have to get the source code out to remember how I did a lot of it.)

The basis of such a system is of course a scheduler where all tasks MUST complete before the next timer tick occurs. I took the inspiration for mine from RIOS ( https://www.cs.ucr.edu/~vahid/rios/ ) which I then refined to add debug printing from a buffer in the "dead" zone, a "run" LED which also served as a simple load monitor, and other niceties. There are of course a few considerations with such a system:

1. obviously all tasks must complete in the allotted time, or you have a fatal error.

2. everything is single thread, so generally atomicity is only a problem for memory objects which are accessed in ISRs. The general rule to only write to shared buffers etc from ONE (higher priority) source serves very well here, but specific cases do need to be thought through.

3. tasks needing finer granularity than the timer tick (in my case, actual generation of pulses for the motors) can operate in higher priority interrupts, driven from additional timers or other sources.

4. If tasks are kept reasonably simple, determining worst case timing is pretty easy - you just measure the worst case for each task, take the worst case sum, and add the worst case time given to ISRs. This for me is the KEY advantage. (No worries about task switching overhead or when certain tasks might pop up and throw things out. They all run, every time.)

5. Obviously blocking in a task (or an ISR) is a complete no-no. Many tasks end up being little state machines.

Eventually the system becomes a group of state machines with separate responsibilities, which communicate via their APIs.

C lends itself to this approach quite well if you see each .c/.h pair as an "object". (These days I might have multiple files in a folder, with only one "external API", to allow for unit testing within a module using Ceedling.) In such a way, separation of concerns and modularity is quite achievable. In modern systems, for instance certain SOC's that combine several embedded processors with FPGA real estate, such an approach could be hugely powerful - one bare metal processor (with hardware support as needed) does the hard RT stuff, the other perhaps runs embedded Linux or similar to provide networking and higher level tasks.

All in all it seems to me that this approach has many advantages over an RTOS, at least until a certain level of complexity, from the point of view of ensuring hard real time performance.

I find it a bit prosaic that Gliwa has entirely passed over such an approach in a book dedicated to the subject of timing in real time systems, and particularly the implication that anything more than the simplest tasks must use an RTOS. For me, one of the key factors in building systems successfully is to select the simplest and most appropriate techniques of "getting it done". I think that Gliwa has fallen back on the "defaults" of the auto industry here (well-proven though they may be) and bypassed a very important class of simpler solutions.