As Will points out, I’m OK if APIs are documented outside of the code
itself. For the OS, I went through and added a bunch of Doxygen
comments, but the function calls and their variants were fairly simple.
Function calls that take big enums as a parameter can be very lengthy to
document with doxygen, and I hate having them in the code itself.
To me, the bigger things that make it easier to learn new APIs are:
- Consistent operation: i.e. don’t have callbacks and event queues,
don’t call functions from multiple different contexts.
- Fewer Function Calls: Easier to learn and remember a few functions,
than 100’s of them. Easier to have sample code cover all our APIs.
- Sample Code: I mostly learn through sample code — i.e. I want to do
something, how do I do it. I have no problem reading relatively complex
source code once I’ve got the basics up & running. But there should
be plenty of sample code to have that easily running.
Sterling
On 11 Jul 2016, at 9:25, Christopher Collins wrote:
On Mon, Jul 11, 2016 at 08:51:10AM -0700, will sanfilippo wrote:
I have mixed feelings about comments. In my view, it is OK to not
comment the code heavily if there is a document that explains the
code. Either is sufficient in my opinion. Of course, keeping to
Doxygen style comments for public API is a good idea. Do we run
doxygen automatically and can we see what the output looks like for
mynewt? I generally use doxygen style comments for all of my
functions
but I have to admit I am not always consistent.
I think comments fall into two broad categories:
1. A specification of a function's or data structure's contract.
2. Explanatory comments that are intended to make code easier to
follow.
The first group of comments generally appear above a function or data
type definition and use the doxygen format. The second group is
usually
in-line with a function body.
In my opinion, comments of the first variety are essential. Someone
should not have to read code just to understand what inputs are
allowed
and whether the function consumes a supplied resource on error, for
example. In my opinion, there is no justification for not requiring
these type of comments.
I don't have a strong opinion about the second kind of comments. On
the
plus side, when they are accurate and up to date, they can be quite
helpful for a person reading unfamiliar code. Unfortunately, these
comments are often inaccurate and out of date, they can a slight
hindrance in reading for someone already familiar with the code, and
worst of all, they make it harder to change code when it needs to be
changed. So I am happy with letting developers use this type of
comment
at their own discretion.
The other thing about comments and documentation: it is not easy to
keep them in sync with the actual code. People change things and then
the comments/documents get out of sync. While this is not a reason to
not document/comment, it can sometimes be worse than having no
comments/documentation.
Agreed. The online documentation will always be out of date unless
there is an automated process to convert comments to documentation.
The issue is always about enforcement; I think we need to have a
conversation about how (and if we should) we enforce adherence to the
coding standards we create.
Insofar as coding standards are useful at all, they need to be
enforced.
If someone thinks an exception is warranted, they should provide
justification in the pull request or commit message.
Yes, this is just a lot of empty talk from me :). I don't know the
right way to enforce coding standards without scaring off
contributors.
Chris
