Coding Conventions

  • Interfaces should be prefixed by an uppercase "I" but otherwise match the implementation type name
  • Enums should not use plural form (never use plural form for anything other than collections)
  • Exceptions should be placed in their own namespace, not the namespace of the classes/scope they are related to (ie: lucere.exception.DirectoryNotFoundException NOT lucere.io.DirectoryNotFoundException)
  • Tests go in the lucere.test project
  • Test case class names should match the associated class, but be suffixed by "Test" and the namespace should also be suffixed with ".test"
    • Example:
    • lucere.io.IDirectory (in lucere.definition project)
    • lucere.io.test.IDirectoryTest (in test project)
  • Mocks should follow a similar convention, and should live in the lucere.test project:
    • Example:
    • lucere.io.IDirectory (in lucere.definition project)
    • lucere.io.mock.IDirectoryMock (in test project)
  • Namespaces should be lower case, but classes, interfaces, methods, properties, etc should be PascalCase
  • Camel case for parameters and private fields
  • Private fields should be prefixed with an underscore
  • All public classes should be public, not sealed, and have an empty constructor

Last edited Nov 15, 2010 at 10:27 PM by geobmx540, version 1

Comments

PrescottNasser Nov 25, 2010 at 8:58 PM 
husey makes a compelling argument.

huseyin Nov 20, 2010 at 6:36 PM 
I also didn't like the lowercase namespace idea.

Think about the source codes of consumers of this library, an example:

using System;
using System.Collections.Generic;
using lucere.io;
using NHibernate;
...

Seems ugly, right? Right.

SergeyMirvoda Nov 18, 2010 at 5:17 PM 
need to define styles for
const
public static readonly fields

andypook Nov 17, 2010 at 9:33 PM 
My apologies for being provocative with the "your train set" comment. Definitely did not intend to add any stress. Your response is of course fair. But... you are the originator and providing guidance and motivation for this project.

"Why be different", answer "Why not?" is probably true in life :-) But, as I understand it, one of the motivations for this project is to have a .Net implementation with .Net conventions (not python, java) so that it feels more familiar to C#/.Net developers. From what I see of other C# projects and guidelines from various sources, with very few exceptions, use PascalCase in these cases. So using a different convention would make it feel unfamiliar.

As you say, this is stylistic not functional and I am just one voice. I do not feel incredibly strongly about the style (though obviously strongly enough to write some comments :) I think the reason that I am persisting here is that I don't want there to be any reason why "people" might reject the library due to not liking the style. I've been places where I wasn't allowed to use a library because it didn't look like .Net. Some reject Lucene.Net because of style reasons.


Cheers,
Andy

paulada Nov 17, 2010 at 9:00 PM 
Hi Troy,

Thanks for spending your time and sharing your arguments! As you could see in my original question, I don't think this is a major concern for Lucere Project, nor a discussion worth bringing to the mailing list. I just wanted to hear from a more experienced programmer (well, this is you) the reason why the convention is different from Microsoft guidelines.

All in all no point in proceeding with this discussion, IMHO.

Thanks,

-- Paulo
By the way, any time you guys need a code-renaming-weekend-attack, you can count on me! : D

thoward Nov 17, 2010 at 7:36 PM 
My goal with providing a standard early on for naming was to avoid ambiguity and avoid spending time discussing these issues. I really don't want to get into a bikeshed discussion on this kind of thing as I consider it a waste of time.

Also, regarding the statement that this project is "my train set". That is simply not the case. I think I've been pretty clear that everything here is open to community discussion and feedback. If the naming standards are a big issue for the community, the naming standard can change, but what is valuable about a naming standard is that it's fixed, unambiguous and easy to understand and easy to comply with.

My personal opinion is that "lower case" is very easy to understand and unambiguous, whereas the rules around Pascal casing are ambiguous, even in the MS published spec. It's notable that Pascal casing in namespaces is only a standard in the .NET world, but in most other programming languages (e.g. Java Python, etc) it's not. This issue is stylistic not functional. I'm mostly concerned with the functional aspects of this library. The function of a namespace is categorical. Categories should not be case sensitive. And to the question "Why be different"... I always answer "Why not?".

If anyone feels that this is a significant issue which must be addressed, feel free to bring this discussion to the mailing list where the community as a whole can take part in it. I encourage you to do this sooner than later, because I'd rather not refactor namespaces across hundreds of files months from now. This is something that should be decided upon before code is written.

Thanks,
Troy

andypook Nov 17, 2010 at 4:13 PM 
On the other hand... No other .Net library does this. They all use PascalCase for Namespace and Class names. It's also the MS recommendation. I believe it is what most C# developers would expect. So it's going to stay out as "different" from other C# stuff like the BCL, NHibernate, MEF, MVC etc etc. Why be different.

On the other hand, it's your train set. As you're leading this project (which I thoroughly congratulate you on starting) you can make your own rules :)

thoward Nov 17, 2010 at 12:42 AM 
There was a discussion about this on the lucere-dev mailing list. In a nutshell it's just my personal coding convention. I prefer it because I find it more readable since it exposes the difference between type names and namespace more clearly.

Thanks,
Troy

paulada Nov 16, 2010 at 12:43 PM 
Hi guys,

Just a minor question. Since you're also .NETfying Lucene, why go lowercase (instead of PascalCase) in namespaces?

Thanks,

-- Paulo