https://gcc.gnu.org/g:9e9ef8522be52093054598d7d92ddc1a1d737f94
commit r16-6879-g9e9ef8522be52093054598d7d92ddc1a1d737f94 Author: Jose E. Marchesi <[email protected]> Date: Sat Jan 17 23:03:34 2026 +0100 a68: new Coding Guidelines manual for Algol 68 This commit adds a new manual containing a few coding guidelines and recommendations for writing Algol 68 code. The primary goal of the document is to be used in the context of GCC development to achieve a coherent style among the code base. However, other people may want to adopt these coding conventions as well, so we are distributing them in their own manual rather than as part of the ga68 internals manual. Thanks to Chris Hermansen, Mohammad-Reza Nabipoor, Pietro Monteiro and 'jpl' James for their help and nice discussions in the algol68@ mailing list. Signed-off-by: Jose E. Marchesi <[email protected]> gcc/algol68/ChangeLog * ga68-coding-guidelines.texi: New file. * Make-lang.in (A68_CODING_GUIDE_MANUAL_FILES): Define. (A68_TEXI_FILES): Add A68_CODING_GUIDE_MANUAL_FILES. (doc/ga68-coding-guidelines.info): New rule. (doc/ga68-coding-guidelines.dvi): Likewise. (doc/ga68-coding-guidelines.pdf): Likewise. ($(build_htmldir)/ga68-coding-guidelines/index.html): Likewise. (algol68.info): Add ga68-coding-guidelines.info. (algol68.srcinfo): Likewise. (algol68.install-info): Likewise. (algol68.install-html): Likewise. (algol68.dvi): Add ga68-coding-guielines.dvi. (algol68.pdf): Add ga68-coding-guidelines.pdf. Diff: --- gcc/algol68/Make-lang.in | 46 +- gcc/algol68/ga68-coding-guidelines.texi | 847 ++++++++++++++++++++++++++++++++ 2 files changed, 885 insertions(+), 8 deletions(-) diff --git a/gcc/algol68/Make-lang.in b/gcc/algol68/Make-lang.in index 49f12eda57da..027ff0c3baf6 100644 --- a/gcc/algol68/Make-lang.in +++ b/gcc/algol68/Make-lang.in @@ -141,7 +141,14 @@ A68_INT_MANUAL_FILES = \ $(gcc_docdir)/include/gcc-common.texi \ gcc-vers.texi -A68_TEXI_FILES = $(A68_MANUAL_FILES) $(A68_INT_MANUAL_FILES) +A68_CODING_GUIDE_MANUAL_FILES = \ + algol68/ga68-coding-guidelines.texi \ + $(gcc_docdir)/include/fdl.texi \ + $(gcc_docdir)/include/gcc-common.texi \ + gcc-vers.texi + +A68_TEXI_FILES = $(A68_MANUAL_FILES) $(A68_INT_MANUAL_FILES) \ + $(A68_CODING_GUIDE_MANUAL_FILES) doc/ga68.info: $(A68_MANUAL_FILES) if test "x$(BUILD_INFO)" = xinfo; then \ @@ -157,18 +164,31 @@ doc/ga68-internals.info: $(A68_INT_MANUAL_FILES) -I $(gcc_docdir)/include -o $@ $<; \ else true; fi +doc/ga68-coding-guidelines.info: $(A68_CODING_GUIDE_MANUAL_FILES) + if test "x$(BUILD_INFO)" = xinfo; then \ + rm -f doc/ga68-coding-guidelines.info*; \ + $(MAKEINFO) $(MAKEINFOFLAGS) -I $(gcc_docdir) \ + -I $(gcc_docdir)/include -o $@ $<; \ + else true; fi + doc/ga68.dvi: $(A68_MANUAL_FILES) $(TEXI2DVI) -I $(abs_docdir)/include -o $@ $< doc/ga68-internals.dvi: $(A68_INT_MANUAL_FILES) $(TEXI2DVI) -I $(abs_docdir)/include -o $@ $< +doc/ga68-coding-guidelines.dvi: $(A68_CODING_GUIDE_MANUAL_FILES) + $(TEXI2DVI) -I $(abs_docdir)/include -o $@ $< + doc/ga68.pdf: $(A68_MANUAL_FILES) $(TEXI2PDF) -I $(abs_docdir)/include -o $@ $< doc/ga68-internals.pdf: $(A68_INT_MANUAL_FILES) $(TEXI2PDF) -I $(abs_docdir)/include -o $@ $< +doc/ga68-coding-guidelines.pdf: $(A68_CODING_GUIDE_MANUAL_FILES) + $(TEXI2PDF) -I $(abs_docdir)/include -o $@ $< + $(build_htmldir)/ga68/index.html: $(A68_MANUAL_FILES) $(mkinstalldirs) $(@D) rm -f $(@D)/* @@ -181,6 +201,12 @@ $(build_htmldir)/ga68-internals/index.html: $(A68_INT_MANUAL_FILES) $(TEXI2HTML) $(MAKEINFO_TOC_INLINE_FLAG) \ -I $(gcc_docdir)/include -I $(srcdir)/d -o $(@D) $< +$(build_htmldir)/ga68-coding-guidelines/index.html: $(A68_CODING_GUIDE_MANUAL_FILES) + $(mkinstalldirs) $(@D) + rm -f $(@D)/* + $(TEXI2HTML) $(MAKEINFO_TOC_INLINE_FLAG) \ + -I $(gcc_docdir)/include -I $(srcdir)/d -o $(@D) $< + .INTERMEDIATE: ga68.pod ga68.pod: algol68/ga68.texi @@ -193,13 +219,14 @@ algol68.srcextra: algol68.all.cross: ga68$(exeext) algol68.start.encap: ga68$(exeect) algol68.rest.encap: -algol68.info: doc/ga68.info doc/ga68-internals.info -algol68.dvi: doc/ga68.dvi doc/ga68-internals.dvi -algol68.pdf: doc/ga68.pdf doc/ga68-internals.pdf +algol68.info: doc/ga68.info doc/ga68-internals.info doc/ga68-coding-guidelines.info +algol68.dvi: doc/ga68.dvi doc/ga68-internals.dvi doc/ga68-coding-guidelines.dvi +algol68.pdf: doc/ga68.pdf doc/ga68-internals.pdf doc/ga68-coding-guidelines.pdf algol68.install-pdf: -algol68.html: $(build_htmldir)/ga68/index.html $(build_htmldir)/ga68-internals/index.html +algol68.html: $(build_htmldir)/ga68/index.html $(build_htmldir)/ga68-internals/index.html \ + $(build_htmldir)/ga68-coding-guidelines/index.html algol68.man: doc/ga68.1 -algol68.srcinfo: doc/ga68.info doc/ga68-internals.info +algol68.srcinfo: doc/ga68.info doc/ga68-internals.info doc/ga68-coding-guidelines.info -cp -p $^ $(srcdir)/doc algol68.srcinfo: algol68.srcman: @@ -245,9 +272,12 @@ $(DESTDIR)$(man7dir)/%.7algol: doc/%.7algol installdirs -$(INSTALL_DATA) $< $@ -chmod a-x $@ -algol68.install-info: $(DESTDIR)$(infodir)/ga68.info $(DESTDIR)$(infodir)/ga68-internals.info +algol68.install-info: $(DESTDIR)$(infodir)/ga68.info \ + $(DESTDIR)$(infodir)/ga68-internals.info \ + $(DESTDIR)$(infodir)/ga68-coding-guidelines.info -algol68.install-html: $(build_htmldir)/ga68 $(build_htmldir)/ga68-internals +algol68.install-html: $(build_htmldir)/ga68 $(build_htmldir)/ga68-internals \ + $(build_htmldir)/ga68-coding-guidelines.info @$(NORMAL_INSTALL) test -z "$(htmldir)" || $(mkinstalldirs) "$(DESTDIR)$(htmldir)" @for p in $(build_htmldir)/ga68; do \ diff --git a/gcc/algol68/ga68-coding-guidelines.texi b/gcc/algol68/ga68-coding-guidelines.texi new file mode 100644 index 000000000000..b8142882cb92 --- /dev/null +++ b/gcc/algol68/ga68-coding-guidelines.texi @@ -0,0 +1,847 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename ga68-coding-guidelines.info + +@include gcc-common.texi + +@synindex tp cp + +@settitle GNU Algol 68 Coding Guidelines + +@c %**end of header + +@c %** start of document + +@copying +Copyright @copyright{} 2026 Jose E. Marchesi. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A +copy of the license is included in the section entitled ``GNU Free +Documentation License''. +@end copying + +@ifinfo +@dircategory Software development +@direntry +* ga68-coding-guidelines: (ga68-coding-guidelines). GNU Algol 68 Coding Guidelines. +@end direntry +This document contains a set of conventions and recommendations for +writing Algol 68 code which is part of ga68, the GNU Algol 68 +compiler. As with any coding conventions, the goal is to achieve a +coherent style among the code base. + +@insertcopying +@end ifinfo + +@c Macro for bold-tags. In TeX and HTML they expand to proper bold words, +@c in other formats it resorts to upper stropping. +@iftex +@macro B{tag} +@strong{\tag\} +@end macro +@end iftex + +@ifhtml +@macro B{tag} +@strong{\tag\} +@end macro +@end ifhtml + +@ifnottex +@ifnothtml +@macro B{tag} +@sc{\tag\} +@end macro +@end ifnothtml +@end ifnottex + +@setchapternewpage odd +@titlepage +@title GNU Algol 68 Coding Guidelines +@versionsubtitle +@author Jose E. Marchesi +@page +@vskip 0pt plus 1filll +@sp 1 +@insertcopying +@end titlepage + +@summarycontents +@contents + +@page + +@ifnottex +@node Top +@top Introduction +@cindex Introduction + +This document contains a set of conventions and recommendations for +writing Algol 68 code which is part of @command{ga68}, the GNU Algol +68 compiler. As with any coding conventions, the goal is to achieve a +coherent style among the code base. + +Algol 68 is probably the programming language with the most carefully +and lovingly designed syntax ever made. It can be verbose when it is +convenient for the programmer, and also extremely compact while +keeping an astounding high level of readability. These conventions +aim to make a good use of that. + +Feel free to adopt our guidelines for your own Algol 68 project, +partially or entirely. + +In what follows we make extensive use of Algol 68 terminology, which +may be confusing at first for the uninitiated reader. The Algol 68 +Jargon File provides definitions for many of the terms used in the +context of the Algol 68 programming language and associated +technologies. If you find yourself wondering about "frobyts" or +"enclosed clauses", please look them up in the jargon +file@footnote{@url{https://jemarch.net/a68-jargon}}. The file is +available online in the www and, in Gentoo, as manpages once you +install the app-doc/a68-jargon package. Just type @command{man 7algol +frobyt} in the terminal, for example. + +Additionally, in this document we use the term "space" and "spaces" to +refer to "typographical display features", i.e. spaces, tabs and +newlines. These characters are of no significance and do not alter +the meaning of the program when they appear between symbols, outside +of string and character denotations, but they have a great impact on +the readability of the code and are the main tool for formatting. + +@menu +* Stropping:: What stropping regime to use. +* Formatting:: Using spaces wisely. +* Comments:: No idem. +* Syntactic Conventions:: How to best write certain constructs. +* Naming:: Choosing good tags and bold words. +* Programming Style:: Recommendations on style. + +* GNU Free Documentation License:: + How you can copy and share this manual. +* Index:: Index of this documentation. +@end menu +@end ifnottex + +@c --------------------------------------------------------------------- +@c Stropping +@c --------------------------------------------------------------------- + +@node Stropping +@chapter Stropping + +The GNU Algol 68 compiler supports two stropping regimes: + +@itemize @minus +@item +The classic @dfn{UPPER stropping}, which is one of the standard +stropping regimes defined in the Standard Hardware Representation for +Algol 68. This regime uses upper-case letters to encode bold letters +and lower-case letters to encode non-bold letters. +@item +The modern @dfn{SUPPER stropping}, which is a GNU extension. This is +the standard stropping regime in GCC, and its rules are similar to the +naming conventions widely used in many modern programming languages. +The resulting programs have a very modern feeling. +@end itemize + +In GCC we use SUPPER stropping only. The only instance of UPPER +stropping are in test cases. Some of the guidelines and +considerations in this document may also be useful in programs using +UPPER stropping. + +@node Formatting +@chapter Formatting + +The placement of spaces and empty lines in the program text plays an +important role when it comes to readability. + +@menu +* Empty lines:: +* Spaces before parentheses:: +* Spaces after parentheses:: +* Spaces within packs:: +* Spaces in row displays:: +* Spaces in formulas:: +* Spaces in declarers:: +* Spaces in indexers and trimmers:: +* Spaces in brief clause forms:: +@end menu + +@node Empty lines +@section Empty lines + +Empty lines are often used in programs to separate logical parts in a +sequence of statements or expressions. This avoids the code to look +like walls of text, which are somewhat difficult to read. This of +course also applies to Algol 68, but to a much lesser degree due to +the exceptionally clean syntax of the language. Therefore we favor a +compact formatting to a reasonable extent. + +Please be frugal with empty lines, especially within enclosed clauses. + +It is not necessary nor advisable to have separated "declaration +parts" in serial clauses, because declarations can appear anywhere. +However empty lines may still be useful to group related declarations +together. + +It is often better to use an explanatory comment rather than an empty +line, again especially within enclosed clauses. + +@node Spaces before parentheses +@section Spaces before parentheses + +Do not put spaces before open-parentheses in routine calls. + +But make sure to always put a space between @code{union} or +@code{struct} and the open parenthesis that follows in declarers. + +Likewise, please put a space before the open parenthesis when the +enclosed clause in a cast is a closed clause. + +Examples: + +@example +@{ No space before open-parentheses in calls @} +puts(fixed(count,0) + "'n"); + +@{ Space between `union' or `struct' and `(' @} +mode Number = union (int,long int,real,long real) + +@{ Space before '(' in casts @} +ref JSON_Fld (fields) := field; +@end example + +@node Spaces after parentheses +@section Spaces after parentheses + +When writing routine texts always place a space between the formal +parameters pack and the mode of the value yielded by the routine. + +When writing operator and procedure declarators do not put a space +between the parameter modes pack and the mode of the yielded value. + +Also in declarers, do not put a space after @code{op} or @code{proc} +and the parameter modes pack. + +@example +@{ Space after formal parameters pack in routine text @} +json_foreach_elem(a, (ref JSON_Val v) void: len +:= 1) + +@{ No space after parameters pack in procedure and operator + declarators @} +proc(string)void error; +@end example + +@node Spaces within packs +@section Spaces within packs + +With "pack" we refer to the following source constructs which are +collections of other constructs enclosed between @code{(} and @code{)} +symbols: + +@itemize @minus +@item The actual parameters in a call. +@item The formal parameters in a routine text. +@item The fields in a struct mode declarator. +@item The modes of the united modes in an union mode declarator. +@item The modes of the parameters in an operator or procedure declarator. +@end itemize + +Spaces are optional after commas in packs when both the preceding and +following symbols are tags. + +Put a space after commas in packs when the next construct is not a +tag, but only if the preceding construct is a tag. + +Do not put spaces before commas in packs. + +Examples: + +@example +@{ Spaces are optional around commas surrounded by tags @} +process(socket, resp, fragmented); +process(socket,resp,fragmented); +op E = (Symbol a,b) bool: a = b; +op E = (Symbol a, b) bool: a = b; + +@{ Space after commas separating a non tag and a tag @} +op E = (Symbol s, Word w) bool: s E w; +mode M = struct (int i, real r); + +@{ No spaces in commas separating non tags @} +proc(int,string,[]real)int callback; +op(int,int)int handler; +mode Data = union (void,bool,int) +@end example + +@node Spaces in row displays +@section Spaces in row displays + +Within row displays spaces are optional after commas, but please never +put spaces before commas. + +@example +@{ Spaces are ok after commas in row-displays @} +[]int a = (1,2,3); +[]int b = (1, 2, 3); +[]string names = ("jemarch", + "mnabipoor", + "pietr0"); +@end example + +@node Spaces in formulas +@section Spaces in formulas + +Do not put spaces after monadic operators whose representation is not +a bold word. + +However, if the monadic operator is represented by a bold word, always +put a space between the operator and the operand, even when the +operand starts with a parenthesis. + +Always put spaces before and after dyadic operators if the formula is +not parenthesized. Spaces are optional if the formula is +parenthesized, provided the operator is not represented by a bold +word. Note however that if long tags are involved extra spaces may be +advisable even for parenthesized formulas. + +Examples: + +@example +@{ No space after non-bold monadic operators @} +int i = -10; + +@{ Always a space after bold monadic operator @} +int i = ABS (base + offset) + +@{ Spaces in dyadic opeator @} +total := a + b; +index := cnt +:= 1; +total := (a + b); +index := (cnt +:= 1); +total := (a+b); +index := (cnt+:=1) +@end example + +@node Spaces in declarers +@section Spaces in declarers + + +Do not put spaces after ']' in row mode declarers. + +Do not put spaces after the bounds of a declarer. + +Also, do not put spaces directly within the bounds of a declarer, +unless for indentation purposes. Since bounds can contain any unit, +the general rules apply within these. + +Examples: + +@example +@{ No space after `]' in declarers @} +[]int a = (1,2,3); + +@{ No spaces after bounds in declarers @} +mode List = [10]int, + MatrixList = [10][3,3]int, + Numbers = []union (int,real); + +@{ No spaces directly within bounds in declarers @} +mode MyString = [1:10@@]MyChar, + DynamicTable = [read_int(10, 20), + read_int(10, 20)]char; +@end example + +@node Spaces in indexers and trimmers +@section Spaces in indexers and trimmers + + +While indexing and trimming a multiple, never put a space between the +indexed tertiary and the SUB symbol. + +Do not put spaces direcly within indexers and trimmers, unless for +indentation purposes. As an exception to this rule, you can put a +single space before the "at" operator @code{@@} if desired. + +Examples: + +@example +@{ No space between tertiary and '[' @} +int i = a[i]; +int i = a[10:20] + +@{ No direct spaces within trimmers and indexers, but before @ @} +[]int a = b[2:5@@10]; +[]int c = d[10:20 @@1]; +@end example + +@node Spaces in brief clause forms +@section Spaces in brief clause forms + +It is generally a good idea to have spaces around @code{|} and +@code{|:} within the brief forms of conditional clauses, case clauses +and conformity clauses. + +When the brief forms are very short and the units are number +denotations, it may be more clear to not use spaces, especially when +the form is an operand in a formula. + +Examples: + +@example +@{ Space around | and |: in brief forms @} +(v | (void): "empty", (bool b): (b | "true" | "false")) + +@{ No spaces may be more readable sometimes @} +int n = 2 + (c>3|10|20); +@end example + +@node Comments +@chapter Comments + +Use @code{"foo"} to refer to formal parameters when documenting +procedures or operators. + +Use @code{`whatever'} to refer to any other source construct that is +not a formal parameter. + +Use @code{@{@{} and @code{@}@}} delimiters for commenting out code. +Remember comments in modern Algol 68 aren't nestable. + +Examples: + +@example +int error_hash = 0; + +@{ Return a hash code for the string "s", or `error_hash' if the string + is too long. @} + +proc hash_string (string s) + +@{@{ int no_longer_needed; @}@} +@end example + +@node Syntactic Conventions +@chapter Syntactic Conventions + +@menu +* Closed clauses:: +* Indexers and trimmers:: +* Conditional clauses:: +* Loop clauses:: +* Case and conformity clauses:: +* Procedure and operator declarations:: +* Contracted declarations:: +* Brief clause forms:: +@end menu + +@node Closed clauses +@section Closed clauses + +Algol 68 allows using @code{(} an @code{)} instead of @code{begin} and +@code{end} to delimit closed clauses. In fact, parenthesized +expression in other programming languages are realized in Algol 68 +with closed clauses, in a very orthogonal way. Both forms are useful +and can generally be used according to the programmer's taste. +However, this section contains a few guidelines and recommendations on +this regard. + +Use parentheses for closed clauses that span a single line, regardless +of the context. Having @code{begin} and @code{end} symbols in the +same line looks weird and confusing. + +As a general rule, always use parentheses in closed clauses that are +operands in a formula. Exceptionally, using @code{begin} and +@code{end} in formula operands may be preferable if the operand +contains many declarations and units, and only if it spans for more +than one line. In this case, however, please consider factoring the +code in the operand into a routine and replace it with a procedure +call. + +The preferred indentation for a closed clause whose contents span more +than one line, and that uses @code{begin} and @code{end} symbols as +delimiters, is to indent the contents right at the right of the +@code{begin} symbol. The @code{end} symbol shall then be placed in +its own line, with the same indentation level than the opening symbol. + +If the closed clause contains empty lines, or if the line preceding +the closed clause is so long that it would "hide" the first line in +the closed clause, then it is ok to put the first unit or declaration +in the line after @code{begin}. This usually happens when the closed +clause is the body of a long routine text. + +The preferred indentation for a closed clause whose contents span more +than one line, and that uses @code{(} and @code{)} symbols as +delimiters, is to indent the contents right at the right of the +@code{(} symbol. The @code{)} symbol finishing the closed clause +shall not be placed in its own line. + +@example +@{ No `begin' and `end' in the same line @} +int i = 2 + (3+4); +int i = 2 + (int i = random(); i % 10 ); +bool test = case v in (string): (puts (s); true) out false esac; + +@{ Closed clauses as formula operands @} +int i = 2 + (int cnt := 0; + to UPB data[@@1] do cnt +:= 1 od; + cnt) +int j = 2 + begin int cnt := 0; + to UPB data[@@1] do cnt +:= 1 od; + cnt + end + +@{ Closed clause with no empty lines @} +begin int fd = fopen ("data', file_o_rdonly") + puts ("first line: " + fgets (fd, 0)); + fclose (fd) +end; + +@{ Closed clause with no empty lines but with preceding + line of similar length @} +proc parse_number = int: +begin + int num := 0; + while num := num * 10 + ABS ch - ABS "0"; + isdigi(getachar) + do ~ od; + ungeachar(ch); + num +end; + +@{ Closed clause with empty lines @} +proc main_proc = int: +begin + @{ Auxiliary procs @} + proc aux1 = int: ...; + proc aux2 = int: ...; + + @{ Computation @} + aux1; + aux2; + + @{ Result @} + aux1 + aux2 +end + +@{ Indentation of closed clauses using `(' and `)' delimiters @} +proc parse_number = int: +(int num := 0; + while num := num * 10 + ABS ch - ABS "0"; + isdigi(getachar) + do ~ od; + ungeachar(ch); + num) +@end example + + +@node Indexers and trimmers +@section Indexers and trimmers + +Algol 68 allows using @code{(} and @code{)} instead of @code{[} and +@code{]} in bounds and slices to represent the SUB and BUS +symbols. This is supported by ga68 via the @option{-fbrackets} +command-line option in order to ease the porting of old code, and it +is disabled by default. Please always use square brackets for indexing +in new code. + +@node Conditional clauses +@section Conditional clauses + +If a conditional clause is still clear and not of excessive length +when written on a single line, just do it. + +Start the enquiry clause in the if-part of a conditional clause right +after the @code{if} symbol, not in the next line. + +The serial clauses in the then- and if-parts of the conditional clause +shall be indented five positions right, which is the length of both +the @code{then} and @code{else} symbols plus one. + +The first declaration or unit in the then- and if-parts shall be +placed in the same line than the @code{then} and @code{else} symbols, +respectively. + +Place the @code{fi} closing symbol in its own line, with the same +indentation level than the matching @code{if}. The exception to this +rule is when the conditional clause has no else-part and the then-part +spans for a single line that is not too long. In that case, place the +@code{fi} in the same line than @code{then}. + +Examples: + +@example +@{ Very small conditional clause in a single line @} +if idx < 0 then fatal("invalid idx") fi + +@{ Short conditional-clause with `fi' in the same line + than `then' @} +if argc /= 3 +then puts("expected two arguments'n") fi + +@{ A conditional-clause that spans several lines @} +if a > 10 +then puts("truncating"); + a := 10 +fi +@end example + +@node Loop clauses +@section Loop clauses + + +If a loop clause is small enough to fit in a single line without +occupying most of it, just do it. + +If a loop clause spans two lines, and the second line is not too long, +you can put @code{od} in the same line than @code{do}. + +If a loop clause spans several lines, please put the @code{do} symbol +in its own line, indented to the same level than the clause's frobyts. + +Examples: + +@example +@{ Very short loop-clause in a single line. @} +for a to argc do puts ("arg: " + argv[a]) od; + +@{ Short loop-clause with `od' in the same line than `do' @} +for i from LWB a to UPB a +do total +:= a[i] od + +@{ A loop-clause that spans several lines @} +while NOT exit +do string cmd = get_command; + process_command(cmd) +od +@end example + + +@node Case and conformity clauses +@section Case and conformity clauses + +Do not write a case or conformity clause in a single line, unless +you are using the brief form. Unlike conditional and loop clauses, +these are difficult to read. + +Please put the @code{in}, @code{out} and @code{ease} symbols in their +own lines, with the same indentation level than the matching +@code{case}. + +Start the choices right after the @code{in} symbol, in the same line. +All the choices may fit in a single line. If they don't, please put +each choice in its own line. + +@example +@{ Short case clause @} +case i +in 100, 200, 300 out 0 esac; + +@{ Long case clause @} +case i +in 100, + 200, + 300 +ouse i % 100 +in 100, + 200, + 300 +esac; + +@{ Long conformity clause @} +case v +in (void): "empty", + (bool b): (b | "true" | "false"), + (string s): s +esac +@end example + +@node Procedure and operator declarations +@section Procedure and operator declarations + +In procedure and operator declarations, if the body of a routine text +starts with 'begin', put it at the same indentation than the +@code{pub}, @code{proc} or @code{op}. Otherwise, indent it three +spaces to the right relative to the @code{pub}, @code{proc} or +@code{op}. + +Examples: + +@example +@{ Body of routine is a `begin'..`end' closed clause @} +proc checked_div = (int a,b) int: +begin + if b = 0 then fatal ("div by zero") fi; + a % b +end; + +@{ Body of routine does not start with `begin' @} +proc checked_div = (int a,b) int: + (b = 0 | fatal ("div by zero"); skip | a % b); + +@{ Body of routine is not a closed clause @} +proc checked_div = (int a,b) int: + if b = 0 + then fatal ("div by zero"); skip + else a % b + fi; +@end example + +@node Contracted declarations +@section Contracted declarations + +Please don't be shy to use contracted forms of declarations. They can +make the program much more readable and they make it easier to add new +declarations, because they prevent writing the same text again and +again. + +However, care should be taken when declaring operators and procedures. +In these cases, contracted declarations should only be used when +declaring very short, one or two lines long routines. The last +routine in the list of joined declarations can be a bit longer. + +Examples: + +@example +@{ Contracted declarations lead to compact and very + readable code @} +int disconnected = 0, connected = 0, unknown = 2; +pub ref JSON_Val json_no_val = nil, + ref JSON_Elm json_no_elm = nil; + ref JSON_Fld json_no_fld = nil; + +@{ Use contracted declarations for short routines @} +op + = (States ss, State s) States: MoreStates (heap States := ss, s), + + = (Transitions ts, Transition t) Transitions: + MoreTransitions (heap Transitions := ts, t) +@end example + +@node Brief clause forms +@section Brief clause forms + +The obvious context where to use the brief forms of conditional, case +and conformity clauses is when these clauses appear as operands in +formulas. They match well with parenthesized closed clauses. + +It is also ok to use brief forms of clauses out of formulas, +especially inside case and conformiy clauses. But please be careful, +as brief forms may be confused sometimes. + +Examples: + +@example +@{ Brief forms in formulas @} +int res = (a=0 | fatal("div by zero"); skip | den/a); + +@{ Brief forms out of formulas @} +for i to ELEMS str +do char newline = REPR 10, tab = REPR 9, c = str[i]; + (c = "\" | res +:= "\\" + |: c = newline | res +:= "\n" + |: c = tab | res +:= "\t" + | res +:= c) +od +@end example + +@node Naming +@chapter Naming + +Unlike most other programming languages, which are not stropped, in +Algol 68 it is possible to have tags with the same name as reserved +words, by appending an underscore character to the tag. For example, a +tag @code{if} can be written as @code{if_}. It is important to note +that the trailing underscore is not part of the tag: it is just a +stropping artifact. This is always better than contriving artificious +synonyms that are often confusing or too long. A copying routine has +arguments "from" and "to"? Call them @code{from_} and @code{to_}. A +struct mode has fields "in" and "out"? Call them @code{in_} and +@code{out_}. + +Please use fully upper-case bold words for operator indicants. This +makes it easier for text editors to highlight them in a different +style than mode indicants, and look more symmetrical in case of dyadic +operators. For example, use @code{ABS} and not @code{Abs}. + +@node Programming Style +@chapter Programming Style + +This section contains some recommendation on the usage of the +facilities of the language. + +@menu +* Writing routines:: +* Nihils:: +@end menu + +@node Writing routines +@section Writing routines + +Use routines liberally! Routines are cheap, very easy to write thanks +to the excellent Algol 68 syntax for routine texts, and first-class +citizens in the language. They also have access to the lexical +environment. So if you find yourself wanting to write a macro in +order to repeat some little calculation, just write a small procedure +or operator instead. + +Choose identifiers that are expressive of meaning in order to clarify +both the intent of the procedure or operator and the code written that +uses it. + +Consider using overloaded operators in preference to procedures with +united mode parameters to encourage users of the operator to create +new versions of the operator for different parameter types, rather +than leaving the users trying to figure out how to hack the united +mode definition. + +The high level of orthogonaliy of Algol 68 combined with the +structural type equivalence and the nice compact syntax of declarers +makes mode names way less relevant than in many other programming +languages. In particular if a routine takes a parameter that is an +united mode, and that particular united mode is either not used +anywhere else or very short, just write the declarer, you don't have +to name it first. + +Please make good use of the lexical block structure of the programming +language: is is there to be used. In little local auxiliary routines, +do not add arguments just to pass a value that is in the environment; +rather, place the declaration of the auxiliary routine near the +declarations of the values it accesses. If this is not possible, then +it may be wise to judiciously pass those non-nearby values as +arguments in order that the programmer be aware that non-nearby values +are being accessed or possibly altered. + +@node Nihils +@section Nihils + +Never use @code{nil} directly in identity relations; it is very error +prone. It is better to define @dfn{nihils} for all reference modes +that are likely to appear in one. + +Examples: + +@example +mode Node = ...; +ref Node no_node = nil; +while n :/=: no_node do ... od +@end example + +@c --------------------------------------------------------------------- +@c GNU Free Documentation License +@c --------------------------------------------------------------------- + +@include fdl.texi + + +@c --------------------------------------------------------------------- +@c Index +@c --------------------------------------------------------------------- + +@node Index +@unnumbered Index + +@printindex cp + +@bye
