Hey All,

I've reworked the servo_control project to be a good example of what I think our code should look like. It is available on the servo-refactor branch of the stm32 repo <https://github.com/psas/stm32/tree/servo-refactor>[1], undor `projects/servo_control`.

We are planning on reviewing the code during the meeting tomorrow night. If you want to give the code a brief skim before the meeting, that would be helpful, but it is not necessary. I'll be driving a fairly broad walk through the code pointing out what I consider to be the most useful changes and we can talk about whether we, collectively, think they are good ideas. Before that, though, I wanted to talk briefly about the three practices I think are most important for us to adopt:

1). *A consistent structure**for source files**. *In the absence of full-blown guided literate source documentation, I think that the best way to increase reader comprehension of source is to structure it consistently. To that end, I think that all source files should contain the following sections, labeled as such by prominent, 80-character-wide comments with two or three preceding lines of whitespace: a) A *Constant Definitions *section, which contains *all* constants defined in the source file. b) A *Global Variables *section, which contains *all* mutable variables that are referred to by more than one function. Each variable *must* have an accompanying comment that explains how it should be used. c) For header files, a *Public Declarations *section that is self explanatory. d) For object files, a *Private Declarations* section for all private (i.e. static) functions that are necessary to support the public API but are not declared in the object file's accompanying header. e) A *Definitions *section containing definitions of all public and private functions (which must have been previously declared in the *Public Declarations *or *Private Declarations* section).

2). *A documenting comment for every function *that justifies the function's existence, explaining how the arguments are used to do whatever it is the function does. If the function modifies or reads any global variables of the file, the comment *must *explain why and how this is done. I find this is very helpful for myself to remember why I wrote the function in the first place when I am making later changes, and for newcomers to the codebase because it not only helps them understand what the function does, but allows them to quickly triage which functions are most important to understand first when they are becoming familiar with the structure.

3). *Code Review*. I find code review to be invaluable because the fresh perspective catches many suboptimal design decisions and bugs (how many times have you figured out the solution to a bug in the course of explaining the problem to someone else?). Beyond that, just knowing that someone else is going to look at my code forces me to hold myself to a higher standard than I often do when working by myself, which results in noticeably nicer code. I understand that things get hectic near launch (though I think that is an argument for why code review during that time is even more important than ever) so we may have to modify things then, but as long as we expect to have more than one person who can understand the STM code at the launch then there is in my mind no excuse to not do it.

I look forward to hearing what you all think about these suggestions tomorrow night!




[1] It is not merged in to master because I need some guidance from K on how to incorporate his recent changes to usbdetail.h before it will work.
psas-avionics mailing list

Reply via email to