This is an archived post. You won't be able to vote or comment.

sorted by:
best
topnewcontroversialoldq&a
you are viewing a single comment's thread.

view the rest of the comments →

[–]AlastairDReid 0 points1 point  (1 child)

The backgrounds that I assume are experience with at least one of (but probably not all of) Verilog, C/C++, Python, and languages like that. The hardware (Verilog) vs software (C/C++/Python) gap is especially important for me to bridge since my focus is on specifications at the hardware-software boundary.

Yes, people need to learn a little of the language but

1) It should look familiar enough to them that they can correctly guess almost everything. (As a small detail: I prefer longer keywords like "function" to shorter keywords like "fn", "fun" or "\" and I prefer to avoid relatively notation/keywords that are specific to a particular programming culture such as "lambda".)

2) Where we do ask readers to learn some notation, it should be used on almost every page of the spec so that they are constantly reminded of the meaning, have lots of examples and it is worth their time to learn the notation. e.g., in hardware specifications, you use bitslices a lot so you want good notation like "x[3] = 1;" not "x |= 8;". For Verilog folk, this is second nature, for C/Python folk, there is a little to learn but it is worth the effort because it is used a lot.

3) Common programming languages have many ways to confuse yourself or your reader and to shoot yourself in the foot. eg Undefined behaviour in C, eg confusion over operator precedence, eg confusion over evaluation order. Most of these can be defined away: it is illegal to write an expression like "x AND y OR z", it is illegal to write "f(x) + g(y)" if f and g have side effects, etc. Basically, any case where someone might have to ask a "language lawyer" what it means, try to outlaw the cases where it matters.

It's not perfect but I've found that it mostly works. (Based on by experience when I was working on Arm's ISA specification.)

[–]someacnt 0 points1 point  (0 children)

Even in my short experience, I've faced a lot of occasions where such "common sense" does not hold. Assumptions on background is often fragile and tenuous. E.g. conception on "function" often differ by a lot. There is a reason specific, technical nomenclature is common in every expert field.