Talk:Ada Programming/Coding conventions

Coding conventions
IMHO, this book should follow the standard coding conventions, e.i. the style of the RM examples: You know, the old style. That is:
 * Keywords are in boldface
 * Identifiers in mixed case, with two exceptions:
 * When interfacing with other languages (like in packages Interfaces.C and Interfaces.COBOL)
 * In Ada 83 every language element was written in upper-case (identifiers, attributes, pragmas...) except keywords.
 * Identifiers of named types do not start with "T" or always end with "_Type" or "_T" (altough the latter is used sometimes, for example in formal parameters of generics, it is not a naming convention for every type).
 * A named access type of another named type has the same name ended with "_Ref", or with "_Ptr" if it is a general access type.
 * The keywords , ... go at the end of the line, and not at the start.

Person; Programmer Object  Person.Object Skilled_In : Language_List; ;    Abstract_Object    ; Class_Member_1 (This :     Object); Class_Member_2 (This :    Object); Class_Member_3 (This :  Object;                              That :     Object); Class_Member_4 (This : Object); Class_Member_5 Object; Programmer;

Some projects use a different code convention (it's only a convention after all), but I think in a tutorial like this we should teach the standard one. The GNAT Coding Style Manual specifies this convention in more detail, altough introduces some rules like: For example:
 * When the if, elsif or else keywords do not fit on the same line with the condition and the then keyword, <tt>then</tt> should be aligned with <tt>if</tt>, and conditions should preferably be split before an <tt>and</tt> or <tt>or</tt> keyword.
 * The same rules applies to while loops (the <tt>loop</tt> keyword aligned with the <tt>while</tt>), subprogram definition (ditto with the <tt>is</tt> keyword)...
 * When a big sentence must be split, put the operator not at the end of that line but at the start of the next one.

long_condition_that_has_to_be_split continued_on_the_next_line ... ;

It also introduces some awkward rules relating to comments, for example, but I think this style manual is a good start, and can be applied even to new Ada 2005 constructions:

Person; Programmer Object  Person.Object Printable.Object Skilled_In : Language_List; ; Programmer;

Another advantage of this coding convention is that we could use the <tt>-gnaty</tt> option of GNAT to enforce these rules. The GNAT Pretty Printer also helps to convert old code to that convention. I propose to use 3 spaces for indentation (See Style Checking), and it is a good idea to use a maximum line size because source code cannot be resized (on small screens this is a problem, and maybe someday it will be printed in a real book!). With the <tt>-gnaty</tt> switch GNAT by default enforces a maximum line size of 79 characters, maybe reducing 10 characters is OK ( <tt>gcc -gnaty -gnatyM69</tt>).

And making a bot (in Ada, of course :-) that watchs for miscompiled examples (syntax only: <tt>-gnats</tt>) or code that do not follows the style guide of the book would be superb.

Well, In my opinion it is important to reach an agreement in this topic, so every one that contributes to this book should express his/her opinion! Thank you!

-- suruena 17:12, 18 Mar 2005 (UTC)


 * I think that having a common style accross the book is desirable but don't have a preference. About keywords I think it is better to use a template rather than directly linking to the keyword page and putting it in bold. See the Spanish wikibook implementation at es:Template:Ada/Reservada. This way not only the text around keywords is reduced but also we can change the face style and link later on. Other question is whether linking to a different page for every keyword or a single page with a section for each keyword (thus linking with #keyword). The second choice has the advantage that all the links will be blue from the beggining. ManuelGR 21:37, 18 Mar 2005 (UTC)


 * Great idea! I was looking for the wikicode equivalent to CSS, to use not only for keywords but also for strings and numeric constants. Templates could be the answer. I've created Template:Adakw for the keywords. I prefer to link every keyword with its own page, but it's true that all those red links are ugly. One possibility is reference the keywords to Programming:Ada:Keywords now, and in the future change the Template to link to its own page (except the table Template:Ada/Keywords, that allways must link to its own page). -- suruena 10:59, 19 Mar 2005 (UTC)


 * Well GNAT Pretty Printer would be good - however is't only available to GNATPro users as AdaCore has not release the sources yet. And it would only work on "working demos" - But then - "working demos" are prefered anyway (I keep them as SourceForge). An automated converter could be put together with AdaCL's Text-Filter-Lib without problem. --Krischik 10:10, 19 Mar 2005 (UTC)


 * I have never heard about that lib. If gnatpp only works with complete examples is a real problem, because few snippets will work. Nowadays the book has few source code, so we could even make every change without a bot, but in the future it will not be so easy. At w:Wikipedia:Bots are listed the requirements, I suppose that our bot could meet all. -- suruena 11:06, 19 Mar 2005 (UTC)


 * I was wrong, the rule that splits a line before an operator comes from the GNU coding conventions, and not from the GNAT Coding Style Manual (in the source code of GNAT the operator is left at the end of the line). I prefer the GNU style (although it is for C :-) because in my opion it's more readable. But the RM uses the other convention, so I think we should use that one. Maybe we could make a section for coding conventions explaining other common ones too (for example, the one that puts the keyword at a new line, like in SPARK). -- suruena 20:44, 29 Mar 2005 (UTC)