Date: Mon, 22 Dec 2014 11:30:05 +1100 (EST) From: Bruce Evans <brde@optusnet.com.au> To: Ian Lepore <ian@freebsd.org> Cc: Andrew Turner <andrew@freebsd.org>, svn-src-head@freebsd.org, Alexey Dokuchaev <danfe@freebsd.org>, src-committers@freebsd.org, svn-src-all@freebsd.org Subject: Re: svn commit: r275961 - head/sys/arm/conf Message-ID: <20141222105500.E911@besplex.bde.org> In-Reply-To: <1419180311.1018.66.camel@freebsd.org> References: <201412201815.sBKIFOSq060122@svn.freebsd.org> <20141221080739.GB27290@FreeBSD.org> <1419180311.1018.66.camel@freebsd.org>
next in thread | previous in thread | raw e-mail | index | archive | help
On Sun, 21 Dec 2014, Ian Lepore wrote: > On Sun, 2014-12-21 at 08:07 +0000, Alexey Dokuchaev wrote: >> On Sat, Dec 20, 2014 at 06:15:24PM +0000, Andrew Turner wrote: >>> Log: >>> Clean up to use the standard style of "options \t" and "device\t\t" >>> >>> options HZ=500 # Scheduling quantum is 2 milliseconds. >>> [...] >>> -options KDB # Enable kernel debugger support. >>> +options KDB # Enable kernel debugger support. >>> # For minimum debugger support use KDB_TRACE, for interactive use DDB. >>> -#options KDB_TRACE # Print a stack trace for a panic. >>> -options DDB # Support DDB. >>> +#options KDB_TRACE # Print a stack trace for a panic. >>> +options DDB # Support DDB. >>> # For full debugger support use this instead: >>> -#options GDB # Support remote GDB. >>> +#options GDB # Support remote GDB. >>> [...] >> >> It also would be nice if we removed trailing dots in comments one day, >> preferreably across all config files we have in the tree. > > Why? I thought our rule about comments is that they're complete > sentences, punctuated as such. That rule is for C source code and doesn't apply to comments to the right of code even there. The rule for options files is to never terminate options or device lines with periods. This rule was broken in only 1 places in the RELENG_4 i386 GENERIC (for the tun device). Also, it is not even broken for 2 options: X options AHC_REG_PRETTY_PRINT # Print register bitfields in debug X # output. Adds ~128k to driver. X options AHD_REG_PRETTY_PRINT # Print register bitfields in debug X # output. Adds ~215k to driver. These lines break many other rules: - that comments to the right of code actually be at the right of code and not spread across multiple lines - that man pages not be written in comments. Especially ones at the right of code where there is less space. - various anti-verbosity rules stricter than the previous one. The i386 GENERIC is still relatively clean, but the breakage of this rule has expanded to include 2 GEOM options, PRINTR_BUFR_SIZE (ick; its description also breaks the line length limit rule), most KDB/DDB options, aic, ie, an, bwi, bwn, ipw, ipi, iwi, iwn, malo, mwl, ral, wi, wl and wpi. aic, ie, an, bwi, iwi, ral and wi also break the line length limit rule. > Of course, I also thought we had a rule that 'device' and 'options' in > kernel config is always followed by two spaces then a tab, so that you > can comment out lines without ruining the indent, and apparently that's > not true either (and I have no idea where I got that notion). The rule for `options' is that it is always followed by _one_ space and a tab. This rule os currently followed by all options lines in i386 GENERIC. `device' lines used to follow Rafferty's rules. They used to be mostly formatted with `device' followed by a single tab, and comments to the right of them lined up in subsections but globally random. This has been cleaned up a bit, at the cost of breaking the line length limit rule in many places. `device' is now consistently followed by _two_ tabs in i386 GENERIC, and comments are consistently lined up starting in column 40 for both `options' and `device' lines. The fancy space+tab rule is less needed for `device' lines, since a single comment character can be prefixed without breaking the formatting. I use this to distinguish local modifications: - GENERIC shouldn't have any commented-out device lines, but i386 GENERIC actually has about 10 (formatted with a single comment character so as not to break the formatting) - local modifications comment out device lines using '# '. This breaks the formatting. NOTES files provide many more bad examples than i386 GENERIC. Bruce
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20141222105500.E911>