Re: [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  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:  [EMAIL PROTECTED]
web:www.agamura.com


___
Mono-list maillist  -  [EMAIL PROTECTED]
http://lists.ximian.com/mailman/listinfo/mono-list

Re: [Mono-list] Coding Standards, etc.

[Pablo Fischer]

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  and all that stuff?

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
> > 
> > 
> >  
-- 
Pablo Fischer Sandoval (pablo [arroba/at] pablo.com.mx)
http://www.pablo.com.mx
http://www.debianmexico.org
GPG FingerTip: 3D49 4CB8 8951 F2CA 8131 AF7C D1B9 1FB9 6B11 810C
Firma URL: http://www.pablo.com.mx/firmagpg.txt

___
Mono-list maillist  -  [EMAIL PROTECTED]
http://lists.ximian.com/mailman/listinfo/mono-list

Re: [Mono-list] Coding Standards, etc.

[Miguel de Icaza]

Hello,

> 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.

Some other people have already pointed you to the Mono coding styles in
/mcs/class/README.  It covers the braces.

We despise hungarian notation, please avoid it.  If somebody has used
that, we will clean it up some day (the reason being: we need the CVS
history more than changing the format, so we rather preserve CVS history
now than changing the code).

We prefer internal variable names to use:

class MyClass {
string my_var;
int my_other_var;

string MyVar {
get { return my_var; } 
}
}

Miguel
___
Mono-list maillist  -  [EMAIL PROTECTED]
http://lists.ximian.com/mailman/listinfo/mono-list

Re: [Mono-list] Coding Standards, etc.

[yoros]

On Sat, Oct 11, 2003 at 04:21:04PM +0200, Malte Hildingson wrote:
> 
> As it stands, those conventions does not match the ones in
> /mcs/class/README and does little to ensure consistency in the class
> libraries at this point. I'm not sure that was what was envisaged here but
> using several, inconsistent conventions probably does not help.
> 
> (I do leave for someone else to decide which is the preferred one however.
> :-)
> 

I think that the best way to get the same coding style is to have an
automated system to parse the sources and get the points where the style
is different.

In the other hand we have the encoding, each file is encoded with a
different encoding (for example CR-LF -> CF). I think that we must have
the CVS server configured to change all CR-LF with Unix style CF and
ensure that the sources are in the same encoding.

Regards,

Pedro

-- 
Pedro Martínez Juliá
\  [EMAIL PROTECTED]
)|[EMAIL PROTECTED]
/http://yoros.dyndns.org
Socio HispaLinux #311
Usuario Linux #275438 - http://counter.li.org
GnuPG public information:  pub  1024D/74F1D3AC
Key fingerprint = 8431 7B47 D2B4 5A46 5F8E  534F 588B E285 74F1 D3AC
___
Mono-list maillist  -  [EMAIL PROTECTED]
http://lists.ximian.com/mailman/listinfo/mono-list

Re: [Mono-list] Coding Standards, etc.

[Malte Hildingson]

As it stands, those conventions does not match the ones in
/mcs/class/README and does little to ensure consistency in the class
libraries at this point. I'm not sure that was what was envisaged here but
using several, inconsistent conventions probably does not help.

(I do leave for someone else to decide which is the preferred one however.
:-)

/malte


On Sat, 11 Oct 2003, Giuseppe Greco wrote:

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

___
Mono-list maillist  -  [EMAIL PROTECTED]
http://lists.ximian.com/mailman/listinfo/mono-list

Re: [Mono-list] Coding Standards, etc.

[Giuseppe Greco]

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:  [EMAIL PROTECTED]
web:www.agamura.com


___
Mono-list maillist  -  [EMAIL PROTECTED]
http://lists.ximian.com/mailman/listinfo/mono-list

Re: [Mono-list] Coding Standards, etc.

[Malte Hildingson]

There are some general guidelines in /mcs/class/README covering (at
least) the issues you mention here, I'm not sure everyone is reading those
however.

On Fri, 10 Oct 2003, 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.
>
>
>
> Thanks,
>
>
>
> Jason
>
>
>
>
> 
> 
>
>
> Jason Raneses
>
>
> Principal Software Engineer
>
>
> Fidelity National Information Solutions:  
> http://www.fnis.com
>
>
>
>

___
Mono-list maillist  -  [EMAIL PROTECTED]
http://lists.ximian.com/mailman/listinfo/mono-list

[Mono-list] Coding Standards, etc.

[Raneses, Jason]

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.

 

Thanks,

 

Jason

 


 
  
  
  
 
 
  
  Jason Raneses
  
 
 
  
  Principal Software Engineer
  
 
 
  
  Fidelity National Information Solutions: http://www.fnis.com