[Xen-API] Re: [PATCH] Just sanitizing indentation in stdext/listext.mli

[Zheng Li <dev@xxxxxxxx>]

On 3/16/2010 2:20 PM, Jonathan Knowles wrote:
> Unfortunately your patch changes the indendation away from
> our coding standard, which says to use tab characters for
> indendation (rather than spaces).
>
> http://wiki.xensource.com/xenwiki/OCaml_Best_Practices says:
>
> "A single level of indenting should consist of a single tab
> character. Spaces should not be used. (Refer to Editing for
> details of how to configure popular editors to conform to
> this requirement.)"
>
> Please could you modify this patch to indent with tabulation
> characters instead of spaces?
>
> Cheers,
>
> Jonathan
Hi,

No intention to invoke flame war on tabs v.s. spaces, but this is by far the 
only OCaml code guideline I've seen that prefers tabs over spaces.

I appreciate the benefit of tab for it's conceptually clean and flexible on 
displaying indentation widths wrt people's different tastes. As far as a piece 
of document uses tabs in a both consistent (not a ugly mix of tabs and spaces) 
and visibly clean manner, I'm happy with it. The problem is I'm not sure source 
code written in the syntax of a language like OCaml can satisfy both 
requirements easily by using tabs alone. At lease, I doubt this is feasible 
without requiring developers to have some rules in mind, considering that both 
the default caml-mode and the tuareg-mode have some space-centric underlying 
implementation...

I followed the trick suggested on the wiki to force the tuareg mode output tabs 
rather than spaces. This is an example produced by the default formatting 
mechanics:

<code>
let·f·x·=$
»   let·z·=·{·aaaa·=·x·;$
»   »   »   ··bbbb·=·x·}·in$
»   z$
</code>

NB. it's shown with the whitespace-mode enabled so that we could clearly identify where are tabs ("»   
") and where are spaces (".") and EOFs ("$").

The tab width is set to 4 in the above. The same code shown with tab width of 8 
looks like

<code>
let·f·x·=$
»       let·z·=·{·aaaa·=·x·;$
»       »       »       ··bbbb·=·x·}·in$
»       z$
</code>

which is obviously unwanted. Of course, here we can solve this particular problem by 
starting a new line before or after the "{" symbol. However there are pitfalls 
elsewhere as well, and you can't really force people to follow these rules unless it's 
always automated with the help of their editors.

Even if a newline is forced before/after "{" or "(" etc., the following example 
is still troublesome (formatted using vi's default ocaml mode):

<code>
let·x·=·($
»   3.1415926535,»  0,»  0,$
»   0,» »   »   »   0,»  0,$
»   0,» »   »   »   0,»  0$
)$
</code>

will obviously become a mess if tab is set to 8 rather than the current 4. 
Forcing a single tab breaks the second requirement: while it might show nicely 
with wider tab width, the current format on narrow tabs will no doubt be 
skewed. A reliable workaround is to use spaces rather than tabs between columns.

I previously use the pure spaces indentation scheme exclusively. After considering the guide line here, I made a switch to the smart tabs rule (http://www.emacswiki.org/emacs/SmartTabs), which should be compatible with tab indentation scheme of XCP project in most simple cases but can also avoid problems above. The idea is fairly simple: using tabs exclusively for (block) indentation, and using spaces exclusively for alignment. I believe the conceptual separation between indentation and alignment makes sense: it allows people to define indentation width as they want but also ensures all code can be displayed correctly everywhere regardless of the viewer’s definition. Most importantly, this has to be automatic! Actually, if we think about the workarounds in the two examples above, they basically justify this principle: the main idea of the workaround in the first example is to shift the part after "{" to the beginning of some block indentation to avoid the situation to align 

with tabs; the workaround in the second example is basically to follow the 
smart tabs rule literally. At the end, the smart tabs rule does mix tabs and 
spaces, but in a clean way.

Just my 2 cents.
--
Zheng



_______________________________________________
xen-api mailing list
xen-api@xxxxxxxxxxxxxxxxxxx
http://lists.xensource.com/mailman/listinfo/xen-api