View source for Coding style/Reindenting

== How to help with the "great reindent" ==

Sign up below at [[#Cleanup coordination]].

* Temporarily modify the [[#Makefile variables]] to try out stuff
* Run the <code>make mark-cstyle</code> and <code>make reindent</code> targets
* Inspect the changes 
** <code>svn diff</code>
** <code>svn diff -x -w</code> (ignores whitespace changes)
** <code>svn diff --diff-cmd=diff -x -uE</code> (ignores untabification changes; requires gnu diff)
** <code>svn diff | cat -et </code> (to show tabs and end-of-line)
* Look for [[#Common failure modes]]
* If stuff gets mangled, reset the affected files to the repository version (<code>svn revert</code>), and try adding exclusions.
* Document exclusions (temporary or permanent) in the tables below at [[#Cleanup coordination]].
* Document additions to <code>$(INDENTDIRS)</code> in the tables as well.
* Commit changes to the trunk (if you have commit access).

== Infrastructure ==

* emacs file-local variable settings
* scripts in src/util
* make mark-cstyle
* make reindent

=== Prerequisites ===

The reindenting scripts require at least GNU Emacs version 22.  Earlier versions of Emacs had versions of CC-Mode that produce variant indentations.  The number of differences is small, though.  Different versions of Emacs have different incarnations of <code>whitespace.el</code> that behave differently and have different interfaces.  The reindenting scripts accommodate for these differences, with a very few exceptions.  (Old-style <code>whitespace.el</code> cleans up mixtures of spaces and tabs anywhere on a line, while the new-style one only does so inside indentation whitespace.)

GNU find (or a reasonably compatible find program that supports the <code>-path</code> and <code>-print0</code> options) is also required, as is an xargs program that supports the <code>-0</code> option.

Python is also needed, though any modern version (2.3 or later) should work.

If the versions of these programs that you are using do not have their usual names, you can override the program names when running make, e.g.

<pre>
make reindent FIND=gfind XARGS=gxargs EMACS=/usr/local/bin/emacs22
</pre>

=== Emacs variables ===

We use various combinations Emacs file-local variable settings to mark what sort of C formatting style a given source file conforms with, as well as for controlling the operation of the reindenting scripts.

This is the standard file-local variable line (at top of file) for marking files expected to fully conform to our "krb5" formatting style:
<pre>
/* -*- mode: c; c-basic-offset: 4; indent-tabs-mode: nil -*- */
</pre>

For BSD-derived code, we use:
<pre>
/* -*- mode: c; c-file-style: "bsd"; indent-tabs-mode: t -*- */
</pre>

=== Makefile targets ===

Running <code>make mark-cstyle</code> will mark certain designated files as the "krb5" style, and certain others as "bsd" style.  At the moment, it uses an explicitly specified group of directories as starting points, but in the future it should start at the top of the source tree and rely on exclusions to tailor its operation.

Running <code>make reindent</code> executes the actual reindenting script, which examines the file-local variable settings in each file.  The steps are:

* Untabify (expand tabs to spaces) if the file-local variable settings specify
* Reindent if the file is marked as conforming to the "krb5" C style
* Perform whitespace cleanup
** Delete whitespace at the ends of lines
** Remove blank lines at beginning and end of file
** Fix up mixtures of tabs and spaces (only if <code>indent-tabs-mode</code> is explicitly specified)

=== Makefile variables ===

<code>$(INDENTDIRS)</code> sets the list of directories that the <code>make mark-cstyle</code> target will operate on.

<code>$(BSDFILES)</code> contains a list of files that the <code>make mark-cstyle</code> target will mark as BSD-style.

<code>$(OTHEREXCLUDES)</code> contains a list of other files or directories to exclude from being marked as krb5-style.

== Common failure modes ==

The most consistently occurring problems when reindenting appear to be:

* Function declarations or similar constructs that have an open-parenthesis as the first non-whitespace character of a line
* Non-conforming block comments, i.e., ones without an asterisk on the left-hand side of each line

== Cleanup coordination ==

Edit the tables to volunteer to evaluate a directory or exclusion.  Use <nowiki>~~~</nowiki> (three tildes) to insert your username in the "who?" cell of a row.  Please see [http://meta.wikimedia.org/wiki/Help:Table] for help with editing MediaWiki tables.  If a table row for a directory name seems too broad, feel free to create new rows specifying subdirectories so that we can divide the work with a finer granularity.

=== Abbreviations/definitions ===

;P/C: Proposed/Committed
;E/F: Evaluate/Fix
;Proposed: means that a directory or file is proposed for addition  to one of the Makefile variables controlling reformatting.  Generally this is meant for use by people without commit access who are volunteering to help with the reindenting effort.
;Committed: means that a given directory or file is listed in the Makefile variable in the version of src/Makefile.in that is already committed to the trunk.
;Evaluate: means that the listed person is going to inspect the file to determine if it should be manually fixed or moved to a permanent exclusion.
;Fix: means that the listed person is going to manually fix the file to remedy any reindenting issues.

=== Directories ===

{| class="wikitable"
|+ directories included in find (<code>$(INDENTDIRS)</code>)
|-
! directory name
! P/C
! exclusions?
! reviewed?
! who?
! comments
|-
| appl || P || N || N || [[User:Ghudson|Ghudson]] ||
|-
| ccapi || || || || ||
|-
| clients || C || N || N || ||
|-
| include || C || Y || Y || [[User:Ghudson|Ghudson]] ||
|-
| kadmin || C || Y || N || ||
|-
| kdc || C || N || Y || [[User:tsitkova|Zhanna]] ||
|-
| kim || || || || ||
|-
| lib/apputuils || || || || ||
|-
| lib/crypto || || || || ||
|-
| lib/gssapi || || || || ||
|-
| lib/kadm5 || C || Y || N || ||
|-
| lib/kdb5 || C || N || N || ||
|-
| lib/krb5 || C || Y || Y || [[User:Ghudson|Ghudson]] ||
|-
| lib/rpc || || || || ||
|-
| plugins || || || || ||
|-
| prototype || C || N || Y || [[User:TomYu|TomYu]] ||
|-
| slave || C || Y || N || [[User:TomYu|TomYu]] ||
|-
| tests || || || || ||
|-
| util || || || || ||
|-
| windows || || || || ||
|}

=== Temporary exclusions ===

Add files or directories here if you need to temporarily exclude them from automatic reindenting (by adjusting the Makefile variables).  For example, the reindenting may badly degrade the formatting of a file; if you notice that, add the file to one of the exclusion lists and try again.  (from a fresh, unmodified copy of the file)

Exclusions here will move to one of the "to keep" tables below once evaluated.  If they are fixed, remove them instead. (from the table, and from the Makefile, if the exclusion was already in a committed version of src/Makefile.in)

{| class="wikitable"
|+ exclusions to eval/fix (<code>$(BSDFILES)</code> or <code>$(OTHEREXCLUDES)</code>)
! directory or file name
! P/C
! E/F
! why?
! who?
! comments
|}

=== Exclusions to keep ===

BSD-marked exclusions are for files of BSD or similar origin, and that should have the formatting preserved in a BSD style for consistency.  "Other exclusions" should be uncommon, but can include source code of external origin or automatically generated source code.

{| class="wikitable"
|+ BSD-marked exclusions to keep (<code>$(BSDFILES)</code>)
! directory or file name
! P/C
! why?
! who?
! comments
|-
| include/gssrpc || C || Sun || [[User:Ghudson|Ghudson]] ||
|-
| include/iprop.h || C || rpcgen || [[User:Ghudson|Ghudson]] ||
|-
| include/k5-platform.h || C || Macros || [[User:Ghudson|Ghudson]] ||
|-
| kadmin/cli/strftime.c || C || BSD || [[User:TomYu|TomYu]] ||
|-
| kadmin/server/ipropd_svc.c || C || rpcgen || [[User:TomYu|TomYu]] ||
|-
| kadmin/server/kadm_rpc_svc.c || C || rpcgen || [[User:TomYu|TomYu]] ||
|-
| lib/kadm5/admin_xdr.h || C || rpcgen || [[User:TomYu|TomYu]] ||
|-
| lib/kadm5/clnt/client_rpc.c || C || rpcgen || [[User:TomYu|TomYu]] ||
|-
| lib/kadm5/kadm_rpc.h || C || rpcgen || [[User:TomYu|TomYu]] ||
|-
| lib/kadm5/kadm_rpc_xdr.c || C || rpcgen || [[User:TomYu|TomYu]] ||
|-
| lib/kadm5/srv/adb_xdr.c || C || rpcgen || [[User:TomYu|TomYu]] ||
|-
| lib/krb5/krb/strftime.c || C || BSD || [[User:TomYu|TomYu]] ||
|-
| lib/krb5/krb/strptime.c || C || BSD || [[User:TomYu|TomYu]] ||
|-
| slave/kpropd_rpc.c || C || rpcgen || [[User:TomYu|TomYu]] ||
|}

{| class="wikitable"
|+ other exclusions to keep (<code>$(OTHEREXCLUDES)</code>)
! directory or file name
! P/C
! why?
! who?
! comments
|-
| lib/krb5/krb/deltat.c || C || Bison || [[User:TomYu|TomYu]] ||
|-
| lib/krb5/unicode || C || Unicode || [[User:TomYu|TomYu]] ||
|}