Dear developers,
I would like to make the following additions to the section on coding
style to developers.txt. Any objections / comments ?
-- Peter
Index: docs/developers.txt
==================================================================---
docs/developers.txt (revision 799)
+++ docs/developers.txt (working copy)
@@ -154,6 +154,10 @@
off the right margin of the screen, expect them to meet the byte
chainsaw sooner or later.
+All types defined with typedef should end in "_t", because this is
+easier to read, and it enables tools (such as indent and emacs) to
+format the source code correctly.
+
Indenting with tabs vs. spaces
------------------------------
@@ -175,6 +179,59 @@
kernel - Documentation/CodingStyle. He's done a far better job of
explaining this.
+Line breaks
+-----------
+
+It is better to have lines that are longer than 80 characters than to
+wrap lines in random places. This makes it easier to work with tools
+such as "grep", and it also lets each developer resize their editor
+window to their own taste, and have their own tab-width, rather than
+being stuck with one particular design.
+
+Of course, this does not mean that lines should be made unnecessarily
+long when there is a better alternative (see the note on
+pretentiousVariableNamingSchemes above). Certainly there should not
+be more than one statement per line. Please do not use
+
+ if (condition) break;
+
+but use the following:
+
+ if (condition) {
+ break;
+ }
+
+Coding style helpers
+--------------------
+
+If you are using emacs, you can automatically adjust the tab-width
+setting to (say) 3 spaces for all NUT sources by putting something
+like this into your .emacs:
+
+ ;; NUT style
+ (defun nut-c-mode ()
+ "C mode with adjusted defaults for use with the NUT sources."
+ (interactive)
+ (c-mode)
+ (c-set-style "K&R")
+ (setq c-basic-offset 3)
+ (setq tab-width 3))
+
+ ;; apply NUT style to all C source files in all subdirectories of nut/:
+
+ (setq auto-mode-alist (cons '(".*/nut/.*\\.[ch]$". nut-c-mode)
+ auto-mode-alist))
+
+You can go a long way towards converting your source code to the NUT
+coding style by piping it through the following command:
+
+ indent -kr -i8 -T FILE -l1000 -nhnl
+
+The following does a reasonable job of converting most C++ style
+comments (but not URLs and DOCTYPE strings):
+
+ sed 's#\(^\|[ \t]\)//[ \t]*\(.*\)[ \t]*#/* \2 */#'
+
Finishing touches
-----------------
On 2/8/07, Peter Selinger <selinger@mathstat.dal.ca> wrote:> +If you are using emacs, you can automatically adjust the tab-width > +setting to (say) 3 spaces for all NUT sources by putting something > +like this into your .emacs: > + > + ;; NUT style > + (defun nut-c-mode () > + "C mode with adjusted defaults for use with the NUT sources." > + (interactive) > + (c-mode) > + (c-set-style "K&R") > + (setq c-basic-offset 3) > + (setq tab-width 3))c-basic-offset of 3 is OK with me, but a tab-width of 3? -- - Charles Lepple
On 2/8/07, Peter Selinger <selinger@mathstat.dal.ca> wrote:> Dear developers, > > I would like to make the following additions to the section on coding > style to developers.txt. Any objections / comments ? > > -- Peter > > Index: docs/developers.txt > ==================================================================> --- docs/developers.txt (revision 799) > +++ docs/developers.txt (working copy) > @@ -154,6 +154,10 @@ > off the right margin of the screen, expect them to meet the byte > chainsaw sooner or later. > > +All types defined with typedef should end in "_t", because this is > +easier to read, and it enables tools (such as indent and emacs) to > +format the source code correctly.I don't oppose to this, but let me point out that the glibc manual discourages the use of "_t" names for types in user code: http://www.gnu.org/software/libc/manual/html_node/Reserved-Names.html#Reserved-Names -- Carlos Rodrigues
On 2/8/07, Peter Selinger <selinger@mathstat.dal.ca> wrote:> bbCharles Lepple wrote: > > > > On 2/8/07, Peter Selinger <selinger@mathstat.dal.ca> wrote: > > > +If you are using emacs, you can automatically adjust the tab-width > > > +setting to (say) 3 spaces for all NUT sources by putting something > > > +like this into your .emacs: > > > + > > > + ;; NUT style > > > + (defun nut-c-mode () > > > + "C mode with adjusted defaults for use with the NUT sources." > > > + (interactive) > > > + (c-mode) > > > + (c-set-style "K&R") > > > + (setq c-basic-offset 3) > > > + (setq tab-width 3)) > > > > c-basic-offset of 3 is OK with me, but a tab-width of 3? > > This does not affect the source code. It affects how your editor > *displays* the source code. To quote from Russell's guidelines: > > > Another thing to notice is that the indenting happens with tabs > > instead of spaces. This lets everyone have their personal tab-width > > setting without inflicting much pain on other developers. If you > > use a space, then you've fixed the spacing in stone and have really > > annoyed half of the people out there. > > So in the sources, all indentation is done by "tab". I like my editor > to display these as 3 spaces (actually, perhaps I prefer 2 spaces, but > that's a matter of taste). > > If you don't set the c-basic-offset equal to the tab-width, then your > indentations will not be saved as one tab per indentation level. > > I hope this clarifies it. The above code snippet is just an example.Ah, OK. I thought there was a third variable that controlled whether or not a string of spaces equal in width to a tab would be collapsed into an actual tab, but I guess that's set by default. This does throw off tables made with tabs, but I suppose that's not a big concern if we use HTML, or if we make sure that tabs are 8 spaces in *.txt documentation files. -- - Charles Lepple