Rules to make code readable

[Reino]

Hi, guys.  (admin, if this post is inappropriate please delete)

So I am doing quite a complicated project (well for my skill level anyway) and my own code is stating to confuse me. Are there any guidelines for writing readable code in embedded development?  I attached my whole project link below. 

my project on github

 

Any tips would be helpful. I am no where near done and the amount of code I have to write is orders of magnitude away from being finished. 

I am using cube IDE for this project. A while ago I did try and transition over to vscode but I was getting a lot of issues with cmake and might have become allergic to it. I have also changed how cube ide looks a bit. below is an screenshot. 

 

tldr

1. tips on orginising code so its easyer for me to follow my own stuff 
2. if you have any tips on making cubeide look better?
3. attached link to my github project below. 

 

 

[Andrew Neil]

This is a general coding question - nothing specific to STM32 or even to microcontrollers.

It’s all been covered at great length in many software-related publications.

Some key things are

• Good naming
• Good organisation - keep it modular: https://en.wikipedia.org/wiki/Modular_programming
• Have a good design before your start coding
• Consistency

https://www.google.com/search?q=code+readability

https://en.wikipedia.org/wiki/Coding_best_practices

 

In addition, learn to use the navigation features in your IDE; eg, in CubeIDE

 

You also have the project explorer (left-hand pane) and the file outline (right-hand pane)

 

What particular challenges are you facing?

[Reino]

sorry I forgot to use the reply function. my reply is below “Its difficult to explain. I stared with ad…..” 

[Pavel A.]

Today this is trivial. Open your project in AI-capable IDE  (enable the Copilot AI in VS Code) and ask it questions. It will explain the code and make interesting suggestions :)

[Reino]

Today this is trivial. Open your project in AI-capable IDE  (enable the Copilot AI in VS Code) and ask it questions. It will explain the code and make interesting suggestions :)

i am using AI to help, but i need to understand whats going on as well. AI is not infallible and it can make mistakes and get stuck in a loop of suggesting the same 3 things that does not solve the problem. usually it then takes me around 1 to 3 hours to figure it out myself. So having the code readable is a must. 

[Pavel A.]

So use a different, better AI. Claude is good.

TL;DR the “traditional” coding culture has been disrupted.

Kind of, you still can make your own bread and pasta at home, and plant your own cucumbers - but this isn’t serious anymore.

[Reino]

Its difficult to explain. I stared with adruino (like most) and moved over to vscode, I wrote all my code in OOP. Vscode and oop I can more easily see more of the code, keep everything in sensible functional “clumps” with oop and i am not entirely sure if vscodes format representation just looks better. 

But now that i am blending c and c++ i have files like my interrupts.c file that just has hal functions in c and i cant see with a glance what going on or what i am looking for. I am struggling to get my head around the same logical grouping like i used to do with the combination of c and c++. I did use a combination of functional and oop back then. 

But looking through my code, does it appear disorganized and unreadable or is my brain just turning into mush? 

[Andrew Neil]

Not sure what you’re meaning by “oop” here ?

OOP - Object-Oriented Programming  - is just an approach to software organisation; it’s not a particular language or toolset.

You can organise C code in an object-oriented way...

[Reino]

yes i mean Object-Oriented Programming, i think i may have just lost the plot and brain turned to mush. It may just be the case that i was not writing my code modular to keep my functions small and in “clumps” the time between my last large arduino project and this large stm32 project is a few years and i lost all my code due to a hard drive format so i cant go back and reference it. 

[Hal3]

This is off topic, but there is a possible surprise gotcha:

Ignition systems generate EMI, sometimes enough to overcome the JTAG pins internal pull up & down resisters. Place 10K or lower pull resisters close to the JTAG pins.

[David Littell]

Don’t post this kind of clutter in an attempt to derail the (already lost) discussion.

[Reino]

So thinking back to the last large project I did (I lost all project files for that one), I was really proud of the way I coded and structured that project. Everything was visible and intuitive and at an glance you can have a idea of what's going on. 

I have forgotten how I did that project and i cant reference it again. I watched a lot of coding videos back then and I think I did all my code very modular keeping functions short with the function names and variables very descriptive of what it does as well. 

So Andrew is correct and I think my brain has indeed turned to mush. Thanks for remining me.