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.
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. 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. Will > On Jul 11, 2016, at 7:58 AM, Christopher Collins <[email protected]> wrote: > > On Thu, Jul 07, 2016 at 04:19:33PM -0400, David G. Simmons wrote: >> As I’m working through all the mynewt code, something I’d love to see >> more of are comments in the code describing what’s going on, etc. I >> admit to not being the best at commenting my code — I’m working on it >> — but it would be really helpful, especially as more contributors join >> the party, to have well documented code so newbies like me can get up >> to speed on what the code is actually doing more quickly. >> >> This would have the adde dbenefit of allowing us to use something like >> Doxygen to auto-generate documentation on the code in a more >> human-readable form. >> >> What do others think of implementing some code-documentation >> standards? > > We definitely need to do a better job with comments. The coding > standards document contains this clause: > > All public APIs should be commented with Doxygen style comments > describing purpose, parameters and return values. Private APIs need > not be documented. > > Do you think the language needs to be stronger or more specific? > > Thanks, > Chris
