Is ST Cube IDE a piece of buggy crap?

[Siwastaja]

What is an "magic numbers"?

A misused term. Your code snippet did not really use magic numbers. The numbers are not unexplained, they refer to the documentation directly. They are also likely to appear only once or twice in code.

A "forced define" is also a code quality problem. When a numerical constant appears once (or even many times, in some cases) in a code, some people out of habit suggest that making it a #define and moving it elsewhere somehow automagically improves code. This is often not the case at all. Especially #defines are not that great since you need to then maintain visibility yourself using #undef, or alternatively get very wide scope.

Comments are better at explaining things than overly long names. Overdefinition leads to duplication and confusion: you have to #define them somewhere, then check elsewhere what the definition is.

Paulca's surficial "review" misses all this. It resembles me of some Programming 101 class. Some people classify all number literals as "magic numbers" which "should be" expressed as constants. This leads to stupidness like calculating circumference as TWO*M_PI*radius or CIRCUMFERENCE_CONVERSION_FACTOR*M_PI*radius, instead of the obviously correct and readable 2*M_PI*radius.

And the only reason M_PI needs to be a #define is that it long to remember and write and appears frequently. These are good reasons.

Avoid cargo cult. When using named constants or #defines improves code, it is usually pretty obvious it does so. In this kind of case it's somewhat ugly anyway, whatever you choose to do.

[paulca]

What is an "apology comment" and "magic numbers"?

Apology comment:  If you feel the need to comment code because it's unclear, then the code is unclear, fix the code.
Magic Numbers:

doStuff(1, 6, 134);

You can look up what those parameters are in the formal definition, but it won't tell you what exactly 1, 6, and 134 are meant to mean.

The solution is to "externalise" static data into named definitions.

doStuff(RETRY, DISABLE_INTERRUPTS,  ALL_CATALOGS);

A more simple example:

doTheThing( false );

const bool debugOutput=false;
doTheThing( debugOutput );

It is highly unlikely the compile will actually bother to allocate that bool.

In the specific case you have at hand, what about:


#DEF CHANNEL_SELECT  | 0<<25
#DEF MEMBURST_SINGLE_XFER | 0 << 23
.... etc.


Then you can do:


DMA1_Stream3->CR = CHANNEL_SELECT MEMBURST_SINGLE_XFER


You could wrap the rather "pure" name: DMA1_Stream3->CR into something more specific to your use.

DisplayDMA_ControlReg = CHANNEL_SELECT MEMBURST_SINGLE_XFER


HAL - for all it's failings - does "try" to follow "self describing code", it's just that they fail miserably because they got embedded programmers to embrace a modern technique.... and we get CR, XFR, BBA, B8T, AAB, CT, XT garbage.

EDIT:  I do agree there is going too far.  I personally don't like C DEFs, especially hierarchies of them.  Worse is when they actually wrap code.  It can, and does in projects I have seen, end up with the maintainer basically defining his own language in macros.  That doesn't help people who understand the underlying language much.

[paulca]

Avoid cargo cult. When using named constants or #defines improves code, it is usually pretty obvious it does so. In this kind of case it's somewhat ugly anyway, whatever you choose to do.

Can we agree that it should be applied as a tool and not a bible?

Peter's project is a one man (and a bit) band.  The full "code hygiene lecture" was probably a bit unnecessary.   It becomes far more important when you have 100 programmers.

[Kjelt]

Peter's project is a one man (and a bit) band.  The full "code hygiene lecture" was probably a bit unnecessary.   It becomes far more important when you have 100 programmers.

Or when an external joins the 1p band or the 1p band wants to outsource the code.
Proper clean coding will pay itself back directly or eventually.

[newbrain]

#DEF CHANNEL_SELECT  | 0<<25
#DEF MEMBURST_SINGLE_XFER | 0 << 23
.... etc.


Then you can do:


DMA1_Stream3->CR = CHANNEL_SELECT MEMBURST_SINGLE_XFER

and get a nice syntax error...
As you hint in the edit, using the preprocessor to change the language is not a good idea.

Magic numbers are not that magic if used once and commented, as in peter-h example.
The text in comments reflects the official reference manual names - so easy to find if a check is needed.

All the following is IMHO and for my personal code, when writing for work (very seldom, nowadays) I 100% abide by the agreed guidelines, like them or not (but I also contribute to them...):
If the same number is used repeatedly and has a meaning unrelated to its value, it might be worth a #define or an enum (for "families" like, say, error codes - this helps in code self-documentation e.g. as formal and actual parameters, and return values).

Code: [Select]

typedef enum SettingsUpdate_
{
    /* modes for SDR settings updates */
    NoUpdate       = 0x00u,
    PipelineUpdate = 0x01u,
    VfoUpdate      = 0x02u,
    BfoUpdate      = 0x04u,
    FilterUpdate   = 0x08u,
    VolumeUpdate   = 0x10u,
    ZoomUpdate     = 0x20u,
    UpdateAll      = 0x3Fu,
} SettingsUpdate;
Here something I wrote a couple of days ago, similar to peter-h's but using CMSIS defines:

Code: [Select]

#define CHAN_TCR (MDMA_CTCR_BWM        /* FIXME: Bufferable? Tentative           */ \
                  | MDMA_CTCR_SWRM     /* Software request                       */ \
                  | MDMA_CTCR_TRGM     /* Full transfer (list + block repeat)    */ \
                  | 0x00000000u        /* PAM: right aligned                     */ \
                  | 0x00000000u        /* PKE: no packing                        */ \
                  | MDMA_CTCR_TLEN     /* Maximum length: 128 bytes (16*64 bits) */ \
                  | MDMA_CTCR_DBURST_2 /* 2^4 beats for destination (maximum)    */ \
                  | MDMA_CTCR_SBURST_2 /* Same for source                        */ \
                  | MDMA_CTCR_DINCOS   /* Double word increment for destination  */ \
                  | MDMA_CTCR_SINCOS   /* Double word increment for source       */ \
                  | MDMA_CTCR_DSIZE    /* Double word size for destination       */ \
                  | MDMA_CTCR_SSIZE    /* Double word size for source            */ \
                  | MDMA_CTCR_DINC_1   /* Increment destination                  */ \
                  | MDMA_CTCR_SINC_1)  /* Increment source                       */
I normally use the vendor's definitions (CMSIS, mostly) for laziness: yes the RM is always open, but auto-completion is quick enough, and shifts are baked in.
The comments are there to tell my future self how the MDMA is setup.

If a set of number is interdependent then a set of related object like macros is useful.

Code: [Select]

#define FFT_DISPLAY_LEN      512 /* This is the actual size of the FFT */
#define FFT_DISPLAY_CENTER   256 /* Center of a full FFT display */
#define FFT_DISPLAY_BOTTOM   128
#define FFT_WATERFALL_HEIGHT 32
#define FFT_WATERFALL_TOP    (FFT_DISPLAY_BOTTOM - FFT_WATERFALL_HEIGHT)

#define FFT_WINDOW_WIDTH  (FFT_FRACTION(FFT_DISPLAY_LEN) | 1) /* Need an odd number */
#define FFT_WINDOW_HEIGHT 128
#define FFT_WINDOW_CENTER (FFT_WINDOW_WIDTH / 2)
#define FFT_WINDOW_X      ((480 - FFT_WINDOW_WIDTH) / 2 + 2) /* Leave a little more space for dB labels */
#define FFT_WINDOW_Y      (300 - FFT_WINDOW_HEIGHT)
0, 1, 2, 10, etc. are in general not in a define, never when used in their mathematical sense (see Siwastaja circumference example).

For some use, the preprocessor is absolutely needed, to reduce typing, and increase readability:

Code: [Select]

/* domain can be D1, D2 or D3 for AXI RAM, SRAM in domain 2 or SRAM in domain 3 */
#define DATA(domain) __attribute__((section(__STRING__(.data.$##domain))))
#define BSS(domain)  __attribute__((section(__STRING__(.bss.$##domain))))
#define FAST_CODE     __attribute__((section(".text.$ITCM")))
#define QSPI_CONST    __attribute__((section(".rodata.$QSPI"))) const

#define DMA_SMALL  __attribute__((section(".noinit.$D2_NCNI"))) alignas(max_align_t)
#define BDMA_SMALL __attribute__((section(".noinit.$D3_NCNI"))) alignas(max_align_t)
#define DMA_LARGE  __attribute__((section(".noinit.$SDRAM_NCNI"))) alignas(max_align_t)

EtA: Ça va sans dire that the 2nd and 3rd examples are going to be replaced by constexpr when I switch to C23, further reducing preprocessor use. The last 4th example, dealing with things outside the C specification (but C23 introduces a standardized attribute syntax and some predefined attributes), will be more or less the only remaining use, with the exceptions of generics or maybe some function like macro when a static inline doesn't cut it.

[paulca]

Q:  Do symbols and code byte length have any impact on the MCU binary?

The answer should justify, or not, the use of abbreviations and their extent in context.

For example.  In most contexts, ctx would be seen as "Context".  ctx_state, ctx_handler, application_ctx, config_ctx.  Great until someone comes up with a "Centre X" and also calls it ctx.  Absolutely the code, if analysed will highlight the difference, however the human mind will NOT voluntarily do analysis, it will go to the quick win every time.  Thus confusion can and probably will occur.  Even if the code in question easily handles this with, or without namespacing.  It will still add cognitive complexity which is to say it adds human error.

In short.  Is there any reason you can't just call the thing "context" and be done with the slight potential of confusion?  It's 4 chars.  Come on.  We have auto complete, you don't even need to type it.

I have worked in code bases written in french, along with the comments.  I could understand it.  I don't speak French.  I have understood and contributed to a code review in Egyptian.  I don't speak Egyptian.

I have worked in code bases written in abbreviations and I was the umpteenth engineer to reply with, "Nope.  Rewrite it.". 

[newbrain]

Q:  Do symbols and code byte length have any impact on the MCU binary?
[...]
I have worked in code bases written in abbreviations and I was the umpteenth engineer to reply with, "Nope.  Rewrite it.".

One of the most common rules of thumb is  to make the length of an object name proportional to its scope.
An iteration variable declared in a short for (size_t i...  statement can be called i and it will not affect readability, it will keep lines shorter (easier to parse) and will be immediately recognized as an index.
A function scope variable named i is, in general, questionable.
I cannot see a good reason to call a file scope or global variable i.

I would never expand MDMA_CTCR_DBURST_2 into MasterDirectMemoryAccess_ChannelTransferConfigurationRegister_DestinationBurst_Bit2
So, yes, it very much depends on the ctx.

[Siwastaja]

Magic numbers are not that magic if used once and commented, as in peter-h example.
The text in comments reflects the official reference manual names - so easy to find if a check is needed.

Yes, this.

I think I can concentrate my point better:

These peripheral registers need long-ish comments to be useful, to the point that you can't replace the comment with a definition. Options are thus:
1) SUPER_LONG_DEFINE_NAME_WHICH_ACTS_AS_APOLOGY_DEFINE_REPLACING_A_COMMENT  <-- not acceptable
2) combination of SHORTER_DEFINE_NAME plus /* extra explaining comment */
3) "magic number" (not really) plus /*comment explaining it*/

Because comment is needed anyway, using the #define won't help remove the need of keeping the code and comment in sync. All it does is spread the mess over larger area in codebase, and add one more symbol to remember. And even the "short" define name will be awkwardly long and repetitive due to pseudo-namespacing you have to do, this is actually my pet peeve and reason I never started using those manufacturer #defines for bitmasks. Proper struct (bitfield) definitions avoid this problem completely.

In other words: boilerplate bad.

I would encourage people to forget this de-facto #define mess and instead choose between proper bitfield structs and "magic numbers" + comments. In other words, use Elegant and Modern Way, or use the Still Living In A Cave way, but only use preprocessor (cavemen on steroids) only when there is no other way.

[paulca]

Q:  Do symbols and code byte length have any impact on the MCU binary?
[...]
I have worked in code bases written in abbreviations and I was the umpteenth engineer to reply with, "Nope.  Rewrite it.".

One of the most common rules of thumb is  to make the length of an object name proportional to its scope.
An iteration variable declared in a short for (size_t i...  statement can be called i and it will not affect readability, it will keep lines shorter (easier to parse) and will be immediately recognized as an index.
A function scope variable named i is, in general, questionable.
I cannot see a good reason to call a file scope or global variable i.

I would never expand MDMA_CTCR_DBURST_2 into MasterDirectMemoryAccess_ChannelTransferConfigurationRegister_DestinationBurst_Bit2
So, yes, it very much depends on the ctx.

Agreed.  The code base in question was written in the 1970s style like so:

_g  meant "Global"

So you had function names like:  _glb() _gxtz()

When it came down to the complicated nitty gritty you were faced with stuff like this:

G_M_XXT( A*2/_gx + _gt )

Oh and again in this case comments, of which there very few, were in French.

"Nope". 

[peter-h]

Well, yes, there are loads of programmers who are just working for a company and don't give a **** whether anybody can read it afterwards, and many view that as job security. If you don't believe me:

I once employed a guy who, every Friday evening, before he went home 1700, deleted a piece of his source code. He then did a touch on it so the last-mod date looked right. He knew that around 1800 I did a tape backup of the whole dev office, and these backups, always whole drives and never incremental, were kept for many months because we had something like 20 tapes in a fireproof safe. Then he left and I had to get somebody to pick up his projects, some of which were in production so we had EPROM masters but the source code was on his PC. We discovered that none of the versions on his PC or on the tapes would build... His mistake was that he didn't always delete the same piece, so we worked it out He used PVCS but did the edit before doing a commit each time.

In Cube IDE (the topic here) ST provide bit names, bit position names, and bit masks. One tends to use these when picking up the "HAL" code, or when using code fragments generated by Cube MX (which the guy working on my project before me liked doing, and it does save time wading through the 2000 page 32F4 RM), but when
writing own code I tend to use numbered bit positions (like in my example above) and comment it very carefully.

Commenting intelligently is crucial because even I find it bloody hard to revisit a project I did a year ago, never mind 10 years ago.

[paulca]

1) SUPER_LONG_DEFINE_NAME_WHICH_ACTS_AS_APOLOGY_DEFINE_REPLACING_A_COMMENT  <-- not acceptable
2) combination of SHORTER_DEFINE_NAME plus /* extra explaining comment */
3) "magic number" (not really) plus /*comment explaining it*/

In other words: boilerplate bad.

1.  Is why we invented namespacing and hierarchical definitions and scope.  Granted C is limited here.
2. SHORTER_NAME in context.
3. Proper code does not need comments.

Boiler plate?  That's what includes are for.  Push it up.

[paulca]

Commenting intelligently is crucial because even I find it bloody hard to revisit a project I did a year ago, never mind 10 years ago.

The science unfortunately shows us that unregulated comments are a primary source of "lint" which leads to bugs.

Formally regulated comments used to generate documentation are far better.

The modern engineering consensus is that well written, readable, well structured code should not need comments.

Personally I am in the more niche camp of that who believes:  "Code should read like English".  This places me in direct opposition to some fairly bespoke language paradigms which seem to have become the next best buzz word.  "Functionally Orientated" produces code that reads like a Math textbook on Information Theory.

[paulca]

Boiler plate?  That's what includes are for.  Push it up.

Replying to myself.

Removal of boiler plate code has been one of the fastest moving areas of software design and engineering over the past 10 years, probably more.

There are techniques.  Primarily the need for the boiler plate is just removed entirely.  The commonalities of boiler plate on a module or project level is defined as the "base convention".  If you write no further code, you will achieve "base convention" functionality.  Language features and design patterns are then used to allow "Overriding the common with the specific."

In MCU land, the way this would work is when you ask for a UART interface, you get one already setup for the majority of the projects usecases.  You the "application use case developer" don't give a damn about how it go created, you just ask for one.  If you need some specific configuration for your usecase, then you use the provided patterns to override the the default "conventional" config.

This is EXACTLY what Arduino Serial does... more or less.

The other modern techniques we use for anti-boiler plate include:
Reversion of control.
Dependency injection
Aspect Orientated Programming patterns.
Annotations.
Build time generated code.
Code as configuration.
Configuration as code.
Externalising config to DBs etc.
Templating.

For case studies.  Look at J2EE - Enterprise Java Bean specification V2.  and the latest version.  You will see a complete night and day difference in terms of boiler plate.  A reduction in about 90% of it.

Spring framework design, ethos, conventions articles and papers would help too.

[peter-h]

Formally regulated comments used to generate documentation are far better.

Not for documentation anybody wants to read

The modern engineering consensus is that well written, readable, well structured code should not need comments.

Only if you want to do what the guy I posted about did...

[Siwastaja]

1.  Is why we invented namespacing and hierarchical definitions and scope.  Granted C is limited here.

Strongly agree. Except that even C is surprisingly good, most of C's crappiness is people expecting C is crappier than it actually is and not using it to fullest. In other words, do what SiliconWizard says, create proper structs using bitfields. Then you have hierarchical namespacing inside structs. You can even use unions and nest structs/unions.


Sure, having enumerated names for values inside the struct's namespace would be the last piece missing, but we can survive without that.

And IMHO we can just ignore the fact that bitfield order is implementation defined. It is not like microcontroller peripheral config registers are portable anyway.

Manual pseudo-namespacing of #defines hurts my soul. THAT is boilerplate, and you can't push it away in a header, you need to repeat it many times for each register access as every bitmask and every shift value has to use the same boilerplate. Copy-paste typos where you use defines from wrong type of peripheral register are very common here.

[Siwastaja]

Proper code almost always needs comments. The purpose is to explain why things work the way they work, rationale for writing the code as it is written.

Example of a typical comment in microcontroller project:
// See STM32F12345 reference manual page 2345:
// It says writing '1' to INVERT_OUTPUT inverts the output of the opamp
// Testing on real prototype revealed this inversion does not work at all.
// Therefore we work around by using PWM values MAX-n instead of n.

Please show me how you are going to convey that in code. I bet you will need "apology defines".

[paulca]

Formally regulated comments used to generate documentation are far better.

Not for documentation anybody wants to read

Rather it's the documentation that people don't want to write and don't want to update in ADDITION to the code.  Again, on top of "self describing code", we have "self documenting code".

In most enterprise libraries you get high-level use-case based documentation with examples and you get the "API Docs.", which are generated from the code and integration descriptors (Swagger/JPA/et.al).  We even generates entity relation diagrams and test plans from there.

If you don't explore the "self documenting code", say by adding the Doxygen plugin to Eclipse for C, in a professional team setting, you will be expected to write that API specification documentation.

Which would you choose?

The modern engineering consensus is that well written, readable, well structured code should not need comments.

Only if you want to do what the guy I posted about did...

Create working software which is robust, easy to develop, easy to adapt, easy to extend, comes in close to budget and close to time, meets any formal or legal regulatory requirements.... etc....etc....   and can be done by a set of 3 teams of 10 people over the next 6 months.  You don't choose the people.

In those 6 months the ENTIRE company, team, management and the customer can change to the point there is no single person remaining who was there at the start.  The project must go on.  Its worth millions.

These are the goals.

I repeat again.  Software Engineering has very little to do with "Programming", although it does try and enforce things upon the later.... often with limited success.

[paulca]

1.  Is why we invented namespacing and hierarchical definitions and scope.  Granted C is limited here.

Strongly agree. Except that even C is surprisingly good, most of C's crappiness is people expecting C is crappier than it actually is and not using it to fullest. In other words, do what SiliconWizard says, create proper structs using bitfields. Then you have hierarchical namespacing inside structs. You can even use unions and nest structs/unions.


Sure, having enumerated names for values inside the struct's namespace would be the last piece missing, but we can survive without that.

And IMHO we can just ignore the fact that bitfield order is implementation defined. It is not like microcontroller peripheral config registers are portable anyway.

Manual pseudo-namespacing of #defines hurts my soul. THAT is boilerplate, and you can't push it away in a header, you need to repeat it many times for each register access as every bitmask and every shift value has to use the same boilerplate. Copy-paste typos where you use defines from wrong type of peripheral register are very common here.

Agreed.  I don't like #define coding.  Actually the whole concept has been removed from nearly ALL subsequent high level languages, along with macros.  They harbour bugs.  They are confusion.  The syntax was written during the alien evasion (or drugs) in the 1970s along with Perl, Procmail, Awk, Sed and the likes.  All of them absolutely smashingly good at the time.

I don't think it's that the concept is "bad", I think it's just a tool which can be over-used, abused and end up obsfucating code to the point nobody can see the bugs for the bugs.

Hierachies of structs and unions is how we did hierarchical defintions for binary "Order messages" in the stock exchange. It's horrific.  Especially when you have to interface across host/network endian boundaries and packing.

On portability. I agree that the micro-controller you are using now is unlike to change it's register bit fields.

What is very likely to happen, is the boss comes in the door and says,

"STM32 Model X is now cheaper.  Make it so."

This was were I was setting out with STM32, having been failed by HAL I wanted to do it myself, for just MY usecases.

Just turns out work, health, other hobbies have denied me that time thus far.

The goal however would be the push all that "what are we, where are we, what config do we need" up into something more common, but not as massive or unnecessary as CubeMX.  The later however I would still continue my approach of "Define my way around it" in such a way as to retain the One way code generation it offers.  Basically I stay out of it's way, it stays out of mine and I can and do often regenerate with CubeMX.

[zapta]

The later however I would still continue my approach of "Define my way around it" in such a way as to retain the One way code generation it offers.  Basically I stay out of it's way, it stays out of mine and I can and do often regenerate with CubeMX.

Can you regenerate from scratch without breaking your build?  CubeMX does require some of your code snippet within the files it generate.

The CubeMX approach of mixing generated and user code in the same file is a nuance.

[Kjelt]

The goal however would be the push all that "what are we, where are we, what config do we need" up into something more common, but not as massive or unnecessary as CubeMX. 

Funny thing is that in 2008 when we had STM8 development and mgt wanted yet another 3rd version of the STM8 for their products and we yet had to rewrite the entire configuration for this 3rd version, we would have jumped from joy to have a visual configurator.
Instead someone created the configuration with X-macro's  This caused some havoc later on as you can imagine but hey.

But then the only thing this visual configurator should do is show a certain microcontroller picture with all options per pin to be visually set (as Cube does) and generate one .h file with that configuration.
Or perhaps a .h file per peripheral that would also be very acceptable.
But unfortunately that is not what Cube does, it generates a shitload of code. Too bad there is not a way in the middle for this.

[paulca]

At Uni while studying UML and "Round trip engineering" we used a "CASE tool" called "Rational Rose"

Rational rose allowed you to take a code base and produce UML entities from it.

If you made changes to the relationships etc, Rational rose could regenerate code from the diagram.

Round and round back and forth.

It also used marker comments where auto generated code lived, so you always had to be careful.

Never used Rational Rose in the wild.  UML hardly gets used except maybe the odd ERD or sequence diagram.

We do use a TON of auto generated code.  In my current project, all APIs are defined in a Swagger YAML, along with their types/payloads etc for validation.  At build time, everything including the REST controllers, message converters, schemas etc are generated from those YAMLs.  What you end up with is stubs to implement or override.

[peter-h]

Cube MX is handy. Once you know your way around it, you can knock up impressive stuff like an HTTP server which presents a page to a laptop, via ETH. Great for impressing the boss What you don't tell him is that this is useless until way more work gets sunk into it.

Similarly you can get USB CDC and USB MSC running fairly quickly. But again, way more work is needed for any real product.

And some of it is buggy and you need to spend a lot of time googling for fixes and applying them. But that is a fairly normal part of a coder's life anyway.

Fortunately my current 32F4 project has an insane amount of functionality, plus expansion via SPI3, so my hope is to not start on a completely new arm32 project in the remainder of my actuarial life

[paulca]

Fortunately my current 32F4 project has an insane amount of functionality, plus expansion via SPI3, so my hope is to not start on a completely new arm32 project in the remainder of my actuarial life

I felt the pain when I created a new project.

debug("Hello World");

Oh... damn.  I need to write or import the debug function from the last project on a different MCU.

That was my first looked at "common" functionality, be it lib.a, be it auto generated, be it copy and paste.  Just so that I don't need to write general housekeeping routines in every project.

Oh course, c&p doesn't work that well between MCU and MCU even in STM32 and even with HAL.

[dietert1]

I think one criterion for a good hardware description (better than long #define files) should be whether the IDE context menus can make useful proposals. This may be possible when using bitfields and enums. If that works it can really help the coder. Seems like most people only work on applications and try to reach the required functionality with the least effort. On the long run it may be more efficient to spend part of our time on constructing reusable code (tools).
E.g. in the IAR environment i can route printf output to the STLink USB CDC interface implementing a small procedure __write(int handle, const unsigned char *buf,size_t bufSize). Having a performant printf channel saves work. I have to be aware that the C runtime calls __write() one character at a time. So i'm using a line buffer for better efficiency. That code is easy to reuse, except i have to configure some UART in CubeMX and connect the MCU RX and TX pins to the STLink pins. Performance depends on implementation details, like using DMA for UART data transfer and a FreeRTOS queue for non-blocking operation.

Regards, Dieter

[paulca]

I think one criterion for a good hardware description (better than long #define files) should be whether the IDE context menus can make useful proposals.

100% agree.  The code base conventions need to work with the IDE of choice.

One particular failure in this is in the HAL code which has been back ported from C++ to C.  The convention used by the converter is to put "methods" as dynamic function pointers in the data structs.  However, Eclipse CDT tools can't follow those "void**" pointers.  They are dead ends.

The other related aspect is autocomplete.  "InteliSense" or other brand name for it.  In enterprise IDEs these are just getting a bit too smart.  When you type:

variable->

They not only give you a list of possible members to access, but the ones you most likely want at the top based on "context".

InteliJ (java based IDE) goes far further, without "online AI", it will not just propose the method formal definition, but it will transpose your local state variables to match the parameters and give you a single auto complete for the rest of the line of code.

The next level up, which I have not yet explored, is letting one of the LLMs to buddy up with you like Clippy.

"It looks like you are filling out a bit field from the STM32 reference manual version 2.04.  Would you like me to complete it for you?"

EDIT:  The reality in my world is that reference manual version 2.04 was found to have a security vulnerability and was immediately deprecated for version 2.05.  Please upgrade.  Changes and impacts below.