Hi Andrew, On Thu, Oct 22, 2020 at 5:07 AM Andrew Butterfield <andrew.butterfi...@scss.tcd.ie> wrote: > > Dear all, > > In the RTEMS Software Engineering manual, Sec 6.3.2.1 > https://docs.rtems.org/branches/master/eng/coding-80cols.html#breaking-long-lines > it recommends excessively long comments be broken as follows: > > /* first line > * second line > * third, and in this case last line */ > > In Sec 6.3.5.2 > https://docs.rtems.org/branches/master/eng/coding-file-hdr.html#fileheadercopyright > we see a copyright and license header which uses the following format > convention: > > /** > * first line > * second line > * third, and in this case last line > */ > > Most RTEMS code I look at seems to follow this second approach, > or the following with only one asterisk on the first line > - particularly the comments that are used to generate Doxygen docs. > > /* > * first line > * second line > * third, and in this case last line > */ > > PS - I prefer this secon/third approach, particularly when the large comment > immediately precedes code. > Correct, the /** is specifically meant for doxygen. (It is the "javadoc" style of comments that doxygen can parse.)
A little bit of grep/regex suggests that inside of cpukit/score we have: 3679 occurrences of /* or /** with */ on the same line 2524 occurrences of /* or /** with no */ on the same line 124 occurrences of /* or /** with some trailing characters and no */ on same line 2400 occurrences of /* or /** with no trailing characters on the same line 2524 occurrences of */ with no /* on the same line (good, that matches from above!) 35 occurrences of */ with preceding non-whitespace characters. So your observation is certainly confirmed. We have not been particular about the comment style, but I think usually we see two-liners with /* first line * second line */ While longer than two-lines tends to follow that /* * first * second * third * etc. */ pattern. Use the /** for doxygen comments. I think it would be fine to go with the empty first/last line. That does seem to be the precedent. > I am developing code (C and Promela) for the qualification activity, Our style guidelines for C code is mainly for the code that is internal to RTEMS. We are fine with any self-consistent style in other contributions (such as BSPs) although code that is meant to be added to rtems.git should strive to follow our style. We are looking at how to make style more easily enforced and maintained by tooling. > and want to start to get this right - so which should I use? For standalone tools it is really your choice. We would prefer adoption of an easily maintained style consistent with some kind of sane default. > > Regards, > Andrew Butterfield > > -------------------------------------------------------------------- > Andrew Butterfield Tel: +353-1-896-2517 Fax: +353-1-677-2204 > Lero@TCD, Head of Software Foundations & Verification Research Group > School of Computer Science and Statistics, > Room G.39, O'Reilly Institute, Trinity College, University of Dublin > http://www.scss.tcd.ie/Andrew.Butterfield/ > -------------------------------------------------------------------- > > _______________________________________________ > devel mailing list > devel@rtems.org > http://lists.rtems.org/mailman/listinfo/devel _______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
