Poor C# get-started docs #25014
Description
This issue is ported from the DevDiv feedback tickets system. Here's the very detailed feedback from Gilberto de Magalhães Falcoski.
C# is wonderful, works very good, BUT: Bad documentation, in fact horrible documentation: Sorry, the documentation of C# is the worst explanation I’ve ever seen!! and I know FORTRAN, basic, cobol, pascal, delphi and others!! I have years of professinal experience in programing, and I say that I have never seen so a terrible explanations! Microsoft, please, write a understandable documentation with clear exemples!!! Some itens are pure junk, for example:
- get started/introduction/types and variables
- get started/introduction/program structure
- get started/types/interfaces
- get started/program building blocks/parameters
- get started/program building blocks/virtual, override and abstract methods
Sorry, really sorry!!!
Details:
- get started/introdution/types and variables
- the exact difference between type and variable, this is not clear!
- in fortran, basic, pascal, etc… there weren’t “types”, there were only “variables”; a variable could be, for exemple, short or long or float. BUT in C# a variable is a type? Where is the meaning of this? Furthermore, everything is a type, a class is a type, a variable is a type, an array is a type, so this is well confused!!
- Please, give the exact definition of a class, of a program, of a namespace, and so on! Please give simple examples so that we can fast understand!!!
- in fortran there was not the concept of “object”, and this is not clear explained, and there are not simple exemples so that we can easily understand! I have understood only with the exemple of the points, in the other item!!! Sorry, but all the explanations are very poor!
- the variables related in this item have a lack of explanation, here we have only the names of the variables, how can this? An overview has only the names, and no explanation!!! This I have never seen!!!
- get started/introdution/program structure
- The exemple Acme.Collections works very well, and we obtain the results 100, 10, 1
- BUT in the exemple “program structure” there are many concepts that were not introduced! So it’s difficult to understand the structure of the program in C#!! For exemple, what is the meaning of along with the name of the class “Stack”? What is the meaning of “T” with the name “Pop”? And so on!!!
- Which are the definitions of class, namespace, type, program, etc…? These parts are not clear, also, when we utilise these parts, WHEN WHEN WHEN? All is very confused, a true mess!!!
- get started/types/interfaces
What is an interface? When we utilise it? Where is a simple example so that we undestand? WHERE IS THE EXPLANATION OF INTERFACE??? In this item, not a single word is understood!
- get started/program building blocks/virtual, override and abstract methods
- Here, there are many concepts that were not introduced! For exemple, “run-time type”, what is this? Everything is a type in C#? Even “run-time” is a type? Sorry, very bad explanations! I have learnt many books of programing, all very good and clear, but so a bad explanation I have never seen. SORRY!
- WHAT IS THIS: “the actual method implementation to invoke”! Please, give an example, what do you mean???
- what a complicated computer language is this C#, I want back the old and simple mbasic, or cobol, fortran, pascal, delphi, sisco, etc…
- sorry, but the program named “Expression”, to explain these concepts is only, and nothing more than, ONLY CONFUSION!!
- first I must inform you that the command “Dictionary<string, object>” doesn’t work!!!
- lets see your bad explanation: an abstract method is a virtual method with no implementation!
- but what is “implementation”? Is it a command? Implementation was not defined!
- but even “virtual method” was not explained (not clearly explained!)
- then how can someone understand what is “abstract method” ???
- what is “run-time type” and what is “compile-time type”? these concepts were not defined!
- THIS IS ANOTHER CONFUSION OF C#: everyting is a type: a class, a method, a variable, a namespace, and so on, BUT WHAT A BIG MESS, ISN’T IT???
- the concepts “run-time” and “compile-time” don’t need explanation, but “run-time type” and “compile-time type” do need a well clear definition, right???
- the concept “expression tree node” was not introduced!! Please, what is this?
- the command line “Evaluate(Dictionary<string, object> vars)” -> what does this do? What do “string” and “object”, in this command line, mean? What do “vars” mean? Oh my God, nothing is explained!!! OH MY GOD, WHAT A CONFUSION!!!
- And the syntax of the command lines, where are they? OH MY GOD, THE SYNTAX, EXPLAIN PLEASE, explain the syntax the syntax!!!
- what is the objectiv of calling the method “Evaluate” in the class “Constant”? If we have a contant, how will you evaluate something??? This is a total nonsense! This has no purpose! NO PURPUSE AT ALL, OH MY GOD, WHAT A BAD EXAMPLE!!!
- the command line "Expression e = new … " was not explained !!! What does this mean? What does the word “new” mean in this command line??? Where is the syntax of the line??? What does the word “vars” mean? MANY THINGS APPEAR SUDDENLY, FALLEN FROM OUTER SPACE!!! HOW IS ANYONE GOING TO UNDERSTAND THIS?
- this command to evaluate (x+3) has the word “new” 3 times!! Why? Which is the syntax of this? You must explain always the SYNTAX SYNTAX SYNTAX , otherwise no one understands nothing!!
- which is the objectiv of using these complicated classes and methods (they can be virtual, abstract, override, etc…) to evaluate X+3 ? This has no meaning !!! This is a true nonsense, yeah, NONSENSE NONSENSE!!!
- where are the syntax of all these commands, like all the other computer languages? I haven’t see any explanation about this!!! Please, explain PLEASE PLEASE PLEASE, explain the syntax!!! THE SYNTAX SYNTAX SYNTAX MUST BE EXPLAINED!!!
- another confusion is the command “override”. About this, there is nothing to understand!
- also another confusion is “class and method”! Please explain clearly when we have a class, when we have a method! Please give definitions about this!!! DEFINITIONS OF CLASS AND METHOD!! When we have a class, when we have a method?? WHEN? WHEN? WHEN???
- What is the meaning of this command line: “vars[“x”] = 3” . This was not introduced yet!!! You must explain the syntax of this, otherwise no one will understand, OK? THE SYNTAX, SYNTAX, SYNTAX, DO YOU KNOW WHAT IS SYNTAX??? YOU MUST LEARN WHAT IS SYNTAX OF COMPUTER LANGUAGE, RIGHT???
- I think that all these explanations that you give, ALL can go direct to GARBAGE CAN, sorry for the frankness!!!
- I think that Microsoft must write everything again! Yeah, everything EVERYTHING AGAIN! I have never seen so a horrible explanation!!!
- Perhaps the language C# is good, but with this horrible documentation we can not use it!!!
- And I have wasted a lot of time with this, so I think I will never use this language C#, I want BACK, PLEASE BACK, the old and the best computer languages COBOL, FORTRAN, MBASIC, PASCAL, DELPHI, SISCO, AND SO ON !!!
Related to the items “Constructors”, “Properties”, “Indexers” and “Events”:
- sorry but the explanations are so bad as the other items
- the explanations use many concepts that weren’t introduced yet
- the syntax of the instructions weren’t explained yet
- for example, the command "MyListlist1 = … " create a list named “list1”, but how is the use of this? How can someone understand this?
- what is the meaning of the angle brackets?
- the term “get accessor” was not defined, please, what is this?
- a constructor can be static or instance constructor: example please!!!
- “the accessor of a property can be virtual”: what is this??? How so?
- you must always explain the syntax, right, THE SYNTAX SYNTAX SYNTAX!!!
- many instructions and words have fallen from outer space suddenly, without explanations!!!
- there aren’t simple and complete examples that explain the ideas
- the explanations are absolute hell, I wasted my time, right?
- Microsoft must write everything again, otherwise it’s impossible to use C#
Document Details
⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.
- ID: 0b0e44dd-e0f2-9ace-006b-479a92fbf424
- Version Independent ID: 7811190e-6019-83d8-d504-c0b985368055
- Content: Define types and their members - A tour of C#
- Content Source: docs/csharp/tour-of-csharp/types.md
- Product: dotnet-csharp
- Technology: csharp-get-started
- GitHub Login: @BillWagner
- Microsoft Alias: wiwagn