Dos And Don'ts: Suggestions for better APIs

[msevestre]

A few suggestions to write better/easier to maintain API. @abdelr @Yuri05 @georgeDaskalakis, please enhance/discuss as you see fit Obviously, these are suggestions. There are cases, where it makes sense to not follow these principles but it should be discussed in PR

DOs

• Use IReadOnlyList/IReadOnlyCollection as return type or parameter of your public APIs instead of IEnumerable
• Create methods such as Add, Remove in your class if you need to modify an internal list instead of exposing the list to the outside world

DON'Ts

• Do not use IList/List as a return type or parameter of public APIs (methods or class member). By using those, you are breaking encapsulation and anyone can modify the list which makes debugging very hard
• Do not use ICache/IDictionary as return type or parameter of public APIs. By doing so, you are duplicating the knowledge of how the key is constructed. This is also a break in encapsulation. Create your own class derived from Cache if you need to use a Cache construct as part of API

[PavelBal]

Topic for coding standards?

[msevestre]

Yes absolutely... once we agree on the content.

[rwmcintosh]

I think we can add all these points. It's what we are already doing every day.

[PavelBal]

@georgeDaskalakis Is there a place for such information in the developers documentation?

[georgeDaskalakis]

@PavelBal if everyone agrees I could add this to the C# coding standards. I feel they belong there - otherwise we could add a page with a title something like suggestions for programmers.

[rwmcintosh]

This is more or less "conventions" the same as the others in that document. Maybe a bit more "best practices" but we also have others that seem a bit more "best practices".

If I wanted to understand what my code should look like before submitting a PR, I'd like it all in one document.

[PavelBal]

So it's a yes`?

[Yuri05]

@PavelBal if everyone agrees I could add this to the C# coding standards. I feel they belong there - otherwise we could add a page with a title something like suggestions for programmers.

agree (coding standards)

[georgeDaskalakis]

Ok, I will create a PR on this and we can discuss there any disagreements- additions regarding the content. ( As Michael noted)