[en] Coding style guidelines

Topics: Announcements
Coordinator
Mar 13, 2011 at 10:15 PM
Edited Mar 13, 2011 at 10:21 PM

Rainbird, I'd like to clarify coding conventions for Zyan. You probably have some sort of style guide (at least in your mind), like this:

  • Root namespace is Zyan, public API class names should also start with Zyan: ZyanConnection
  • .NET library design guidelines is a recommended minimum (Pascal casing for all public members, etc)
  • Hungarian notation is explicitly prohibited ;)
  • Private fields are camel-cased with underscore prefix (_wireTypeCache), method arguments without prefixes
  • C# 3.0 syntax is preferrable (automatic properties, initializers, lambdas, var keyword, LINQ, etc)
  • Non-generic collections are obsolete (should only be uses to deal with legacy APIs)
  • Warnings are treated as errors
  • All public members are XML-documented
  • ... more?

I've seen a few files (like CryptoClientChannelSink.cs, for example) where tabs are mixed with spaces. You probably switched to spaces later, so all new files are indented using spaces.

Please consider using tabs for indentation. Tabs are adjustable, spaces aren't. Tabs allow team members to set any indent size they like (I usually set tab to 3 spaces, standard size is 4, and there was a guy in my company who used 8 spaces per tab, huh). If you dislike tabs for some reason, I'll use separate VS settings for Zyan, no big deal.

Another question is primary XML documentation language. As far as I know, there is no multi-language support in C# XML comments. It would be cool to have some lang="en" or lang="de" in <summary> tag, but alas, there is no way to deal with it.

What do you think about gradually switching to English? I don't believe Zyan was designed for German developers only :)

Coordinator
Mar 14, 2011 at 7:26 AM

> ... more?

No, I think you already listed all.

> Please consider using tabs for indentation.

Normally, I use tabs. Some snippets are older than Zyan an partly edited with some text editor. That´s the reason for the mixed space/tab usage.

>  I don't believe Zyan was designed for German developers only :)

Zyan was born from the idea to use the Event Based Components architecture model from Ralf Westphal for creating distributed applications in a easy way. First it was only a small spike solution to test distributed EBC. Later I decided to create Zyan as a general communication framework and published it to codeplex. Not only for German developers, of course.

> What do you think about gradually switching to English?

I already thought about that. Because Zyan ist now international, we should use English as project language. I´ll translate the existing XML member documentation in code step by step and remove the most inline comments. Many of them makes no sense, when translated to English, because C# keywords are English too.

You may have noticed that I write German comments for almost every line of code. I always write the comment before I write the code. So I have to word a comment sentence. This forces me to think about what I want to code. Often I decide to do it different while finding the right words for the comment line.

But this not a coding convention or some like that. We switch to English for all comments. That is easier for everyone. But it will take some time to translate the existing code comments. Please be patient.

Coordinator
Mar 14, 2011 at 12:36 PM

>Zyan was born from the idea to use the Event Based Components architecture model from Ralf Westphal
>for creating distributed applications in a easy way. First it was only a small spike solution to test distributed EBC.

By the way, there are two Ralf Westphal's EBC toolkits available here on codeplex: Event-Based Components Binder and Event-Based Components Tooling. I'd reference them in Zyan documentation for futher reading on EBC subject (both projects contain some overview of EBC model in English).

>I´ll translate the existing XML member documentation in code step by step and remove the most inline comments.

That would be great! Many thanks in advance.

>But it will take some time to translate the existing code comments. Please be patient.

Of course, I understand it would take some time. I don't think it's top-priority task :)

Coordinator
Mar 15, 2011 at 12:27 AM

> By the way, there are two Ralf Westphal's EBC toolkits available here on codeplex: Event-Based Components Binder and Event-Based Components Tooling. I'd reference them in Zyan documentation for > futher reading on EBC subject (both projects contain some overview of EBC model in English).

The EBC Binder works only in very limited scenarios. Last check-in was Mar 2010. But the EBC Tooling is very interessting because it contains an EBC diagram visualizer and a EBC designer plug-in for Visual Studio. I know that project from an article inside the German developer magazine DOTNETPRO and Ralf´s Blog.