[Mono-list] Coding Standards, etc.

[Giuseppe Greco]

Hi Pablo,

On Sun, 2003-10-12 at 01:56, Pablo Fischer wrote:
> Hi!
> 
> Well reading that C# GuideLines
> (http://developer.agamura.com/technotes/csharp-coding-guidelines/) and
> in the section for comments appears a comment (duh!) that say that it's
> not so good to use the C# Document Style (the three slashes) so Why its
> so necesarry tu use the <summary> and all that stuff?

Here below are some interesting comments issued by Miguel:

>>> Miguel said <<<
Monodoc is the framework to document the Mono class libraries, so we
have slightly different needs than the documentation typically embedded
in C# code.   There were various reasons why Mono as a project
decided a few months ago to use the ECMA XML file format as its master
file format as opposed to the C# markup, and they are:

        * Internationalization issues: documentation embedded in the
          source code is only available in one language.  This possed
          a problem: documentation for other languages had to be kept
          on separate files, so we had to define a file format for this.

          Basically, it would not be practical to have documentation in
          30+ languages in the source code.   

          It would also not be practical to track updates to the
          documentation if it were to be embedded.

        * Inline documentation is best to document the workings of the
          code and not necessarily the exposed API.  It might work for
          smaller projects, but it becomes a liability to maintain the
          code to include all the documentation inline in our opinion.
        
          Rotor's API documentation are a good proof of this: the
          documentation is actually just "linked" from the main source
          code, I imagine that they also encountered this problem.

        * Using the format that the ECMA group used to define the API
          meant that we could bootstrap our documentation effort
          quickly.  We have since extended this format to suit the needs
          of Mono better (Some changes were done by Duncan, and more
          recently Joshua Trauber has updated its format).

Miguel
>>> End <<<

I fully agree with Miguel, so that's why in our C# guidelines we
discourage the use of inline documentation comments.

Gius_.

> thanks!
> 
> El sáb, 11-10-2003 a las 05:57, Giuseppe Greco escribió:
> > On Fri, 2003-10-10 at 18:02, Raneses, Jason wrote:
> > > Has anyone published any documentation on what coding standards Mono
> > > source should follow?  I am mainly concerned about the use of
> > > Hungarian notation and the placement of brackets in the source.  There
> > > are a lot of inconsistencies in the CVS source I’ve inspected.
> > 
> > Here's an alternative:
> > 
> > http://developer.agamura.com/technotes.html
> > 
> > I hope that helps,
> > 
> > Gius_.
> > 
> > > 
> > >  
> > > 
> > > Thanks,
> > > 
> > >  
> > > 
> > > Jason
> > > 
> > >  
> > > 
> > > ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
> > > 
> > > Jason Raneses
> > > 
> > > Principal Software Engineer
> > > 
> > > Fidelity National Information Solutions: http://www.fnis.com
> > > 
> > > 
> > >  
-- 
----------------------------------------
Giuseppe Greco

::agamura::

phone:  +41 (0)91 604 67 65
mobile: +41 (0)76 390 60 32
email:  giuseppe.greco@agamura.com
web:    www.agamura.com
----------------------------------------