Towards L T EX Coding Standards A Not L A T EX ones? What can - PowerPoint PPT Presentation

L A T EX Style Didier Verna Introduction Coding Standards? Towards L T EX Coding Standards A Not L A T EX ones? What can we do? Layout Blanks Names Didier Verna Design Duplication Conditionals didier@lrde.epita.fr Modularity http://www.lrde.epita.fr/˜didier Behavior Key/Value interfaces Intercession TUG 2011 – Thursday, October 20 Social Conclusion Perspectives 1/37

Table of contents L A T EX Style Introduction Didier Verna 1 Introduction Coding Standards? Level 1: layout 2 Not L A T EX ones? What can we do? Layout Level 2: design 3 Blanks Names Design Level 3: behavior 4 Duplication Conditionals Modularity Level 4: social Behavior 5 Key/Value interfaces Intercession Social Conclusion 6 Conclusion Perspectives Perspectives 7 2/37

History L A T EX Style 1918 The Elements of Style , William Strunk, Jr. and E.B. Didier Verna White (4th edition 1999). Style guide for writing Introduction American English. Coding Standards? Not L A T EX ones? 1974 The Elements of Programming Style , B.W. Kernighan What can we do? and P .J. Plauger, McGraw Hill (2nd Edition 1978). Style Layout Blanks guide for programming. Names Design . . . The Elements of whatnot Style . Duplication Conditionals Modularity Behavior Key/Value interfaces Intercession Social Conclusion Perspectives 4/37

Purpose L A T EX Style help programmers to read and understand source code Didier Verna not only their own but that of others Introduction From the GNU Coding Standards: Coding Standards? Not L A T EX ones? What can we do? Their purpose is to make the GNU system Layout Blanks clean, consistent, and easy to install. This Names document can also be read as a guide to writing Design Duplication portable, robust and reliable programs. Conditionals Modularity Behavior Key/Value interfaces Intercession Social Conclusion Perspectives 5/37

The coding standards many-festos L A T EX Style - Readability Didier Verna - Maintainability - Robustness Introduction - Reliability Coding Standards? \relax Not L A T EX ones? \keepcool What can we do? \takeiteasy Layout Blanks Names Design Duplication Conditionals Modularity Behavior Key/Value interfaces Intercession - Portability - Extensibility Social - Intercession Conclusion Perspectives Consistency: the exact coding style is less important than actually sticking to it! 6/37

30 years and no style? . . . makes L A T EX a dull toy. . . L A T EX Style Legacy Didier Verna ◮ Learning by example (learn the good and the bad) Introduction Lack of help Coding Standards? ◮ Liberal language (macro-expansion) Not L A T EX ones? What can we do? ◮ Editor support (complicated) Layout Lack of need Blanks Names ◮ A world of dwarfs Design Duplication (T EXLive 2009: average 327 LoC, median 134 LoC) Conditionals ◮ Antisocial development Modularity Behavior (most packages single-authored) Key/Value interfaces Intercession Social Conclusion Perspectives 7/37

30 years and almost no style? . . . makes L A T EX an almost dull toy. . . L A T EX Style Tools Didier Verna ◮ Blank lines, comment syntax ◮ calc , ifthen , doc , ltxdoc etc. Introduction Coding Standards? Conventions Not L A T EX ones? What can we do? ◮ \usepackage vs. \RequirePackage , Layout @ character etc. Blanks Names ◮ L A T EX itself not even conformant ( e.g. \hbox , \m@ne ) Design Companion Duplication Conditionals ◮ Section 2.1 (Structuring of source files) Modularity ◮ Section A.4 (Structuring of package files) Behavior Key/Value interfaces ◮ Less than 1% of the book. . . Intercession Social Conclusion Perspectives 8/37

The need for coding standards is real L A T EX Style Why? Didier Verna ◮ Learning by good example ◮ Facilitate interaction Introduction Coding Standards? ◮ Clean up the current intercession mess Not L A T EX ones? What can we do? How? Layout ◮ Level 1 (low): layout – formatting, indentation, naming Blanks Names schemes etc. Design ◮ Level 2 (mid): design – modularity, encapsulation, other Duplication Conditionals paradigms etc. Modularity ◮ Level 3 (high): behavior – user interfaces, package Behavior interaction / conflict management etc. Key/Value interfaces Intercession ◮ Level 4 (meta): social Social Conclusion Perspectives 9/37

Blanks Be spacey L A T EX Style 1 Stay WYSIWYGly coherent Didier Verna ◮ \\ , \par ◮ Tabular-like environments ( & , \\ ) Introduction Coding Standards? 2 Put only one “logical” instruction per line Not L A T EX ones? What can we do? ◮ environment calls Layout ◮ \expandafter\foo\bar Blanks Names ◮ \raggedleft\foo\bar baz Design 3 Be as spacey as you like in math mode Duplication Conditionals ◮ blanks ignored Modularity Behavior 4 Grouping ( any kind) = ⇒ indentation Key/Value interfaces Intercession ◮ {} , \b[egin]group \e[nd]group , Social \makeatletter , \makeatother etc. Conclusion 5 The % character is your friend! Perspectives 11/37

Example Choose your preferred style. . . L A T EX Style Didier Verna \ def \ @docinclude#1 { \ clearpage \ if@filesw \ immediate \ write \ @mainaux { \ string \ @input {#1. aux } } \ f i \ @tempswatrue \ if@partsw \ @tempswafalse \ edef \@tempb{ # 1 } \ @for Introduction \@tempa: = \ @partlist \ do { \ i f x \@tempa\@tempb\ @tempswatrue \ f i } \ f i Coding Standards? \ if@tempswa \ l e t \ @auxout \ @partaux \ if@filesw Not L A T EX ones? \ immediate \ openout \ @partaux #1.aux What can we do? \ immediate \ write \ @partaux { \ relax } \ f i % . . . \ f i : − ( Layout Blanks Names Design \ def \ @docinclude #1{ Duplication \ clearpage Conditionals \ if@filesw \ immediate \ write \ @mainaux { \ string \ @input {#1. aux } } \ f i Modularity \ @tempswatrue \ if@partsw Behavior \ @tempswafalse Key/Value interfaces \ edef \@tempb{#1} Intercession \ @for \@tempa: = \ @partlist \ do { \ i f x \@tempa\@tempb\ @tempswatrue \ f i } Social \ f i \ if@tempswa Conclusion \ l e t \ @auxout \ @partaux \ if@filesw Perspectives \ immediate \ openout \ @partaux #1.aux \ immediate \ write \ @partaux { \ relax } \ f i % . . . \ f i : − ) 12/37

Braces for impact! Where do you put them? L A T EX Style Hmmm ok Didier Verna \ newenvironment { env } [ 1 ] \ newenvironment { env } [ 1 ] Introduction { % { % Coding Standards? \ opening \ code \ opening \ code Not L A T EX ones? \ opening \ code \ opening \ code What can we do? } } { % { % \ closing \ code Layout \ closing \ code \ closing \ code Blanks \ closing \ code } Names } Design Duplication Conditionals Ouch! ok Modularity Behavior \ newenvironment { env } [ 1 ] { % \ newenvironment { env } [ 1 ] { % Key/Value interfaces \ opening \ code % % \ begin { env } { opt } Intercession \ opening \ code } { % \ opening \ code Social \ closing \ code \ opening \ code } { % \ closing \ code } % % \ end { env } Conclusion \ closing \ code \ closing \ code } Perspectives Note: brace position may require eol % char 13/37

Exceptional situations / oddities No rule without exception L A T EX Style Forced indentation Didier Verna \ @ifnextchar [ %] syntax screwup ! Introduction { \ @fxbeginsenv { # 2 } } { \ @@fxbeginsenv { # 2 } } } Coding Standards? Not L A T EX ones? What can we do? Layout \ @ifnextchar [ %] syntax screwup ! Blanks { \ @fxbeginsenv {#2}} Names { \ @@fxbeginsenv { # 2 } } } Design Duplication Conditionals Empty body-like macro arguments Modularity Behavior Key/Value interfaces \ @ifundefined {#1 note } { } { % Intercession \ @fxpkgerror {command p r e f i x ’#1 ’ already in use } { % You have called \ string \ FXRegisterAuthor \ space with a command p r e f i x Social already in use . \ MessageBreak Conclusion Please choose another one . } } Perspectives 14/37

How maniac can you be? Inter-macro indentation L A T EX Style Didier Verna \ newcommand \ t e x t { % \ @nextentry \ noalign \ bgroup Introduction \ gdef \ @beforespace { \ subrubricbeforespace } % Coding Standards? \ @ifstar { \ @stext } { \ @text } } Not L A T EX ones? What can we do? \ newcommand \ @text [ 1 ] { % Layout \ gdef \ @nextentry { } % \ egroup % end of \ noalign opened in \ t e x t . Blanks \ multicolumn { 3 } {@{ } p { \ linewidth }@{ } } { \ @rubrictextfont # 1 } \ \ } Names Design \ newcommand \ @stext { % Duplication \ gdef \ @nextentry { \ egroup \ \ \ par } % Conditionals \ egroup % end of \ noalign opened in \ t e x t . Modularity \ multicolumn { 3 } {@{ } p { \ linewidth }@{ } } \ bgroup \ @rubrictextfont } Behavior Key/Value interfaces Intercession Social Conclusion Perspectives 15/37

Names You get one for life, so beware. . . L A T EX Style 1 Use prefixes Didier Verna ◮ Avoid name clashes ( e.g. \text in C ur V e and siunitx ) ◮ Mandatory for styles, arguable for classes Introduction Coding Standards? ◮ Use one and stick to it! Not L A T EX ones? ( \finkdir vs. \fnk@maindir ) What can we do? Layout 2 Use postfixes (beware the \new* commands!) Blanks Names ◮ \newsavebox\myitemsBOX Design vs. \newcounter{myitems} Duplication Conditionals 3 From the Companion Modularity ◮ Lowercase for API Behavior Key/Value interfaces ◮ Mixed case for extension API Intercession ◮ @ character for internals (several levels) Social 4 But stop the m@dness ! Conclusion Perspectives ◮ \@latexerr , \@latex@error ◮ \@input , \@@input , \@input@ , \@filef@und ◮ \sixt@@n , \g@addto@macro 16/37