Coding conventions

IMHO, this book should follow the standard coding conventions, e.i. the style of the RM examples:

• 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 is, then... go at the end of the line, and not at the start.
• ...

You know, the old style. That is:

with Person;

package Programmer is

   type Object is new Person.Object with 
      record
         Skilled_In : Language_List;
      end record;

   type Abstract_Object is tagged null record;

   procedure Class_Member_1 (This : in     Object);
   procedure Class_Member_2 (This :    out Object);
   procedure Class_Member_3 (This : in out Object;
                             That :    out Object);
   procedure Class_Member_4 (This : access Object);
   function  Class_Member_5 return Object;

end 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:

• When the if, elsif or else keywords do not fit on the same line with the condition and the then keyword, then should be aligned with if, and conditions should preferably be split before an and or or keyword.
• The same rules applies to while loops (the loop keyword aligned with the while), subprogram definition (ditto with the is 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.

For example:

while long_condition_that_has_to_be_split
      and then continued_on_the_next_line
loop
   ...
end loop;

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:

with Person;

package Programmer is

   type Object is new Person.Object
                  and Printable.Object
   with 
      record
         Skilled_In : Language_List;
      end record;

end Programmer;

Another advantage of this coding convention is that we could use the -gnaty 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 -gnaty switch GNAT by default enforces a maximum line size of 79 characters, maybe reducing 10 characters is OK ( gcc -gnaty -gnatyM69).

And making a bot (in Ada, of course :-) that watchs for miscompiled examples (syntax only: -gnats) 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 is keyword at a new line, like in SPARK). -- suruena 20:44, 29 Mar 2005 (UTC)