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
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
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
 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