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
