[BBeck]

mod edit:
This discussion was split from this thread.

---

I agree that you should get out there and experiement. You can't break the computer unless you're deleting files or something (and then it would only be if you're deleting system files which the OS should prevent you from doing anyway). Try it. Watch it blow up. Then ask why it blew up or did something other than what you expected.

But you also shouldn't be afraid to ask questions here on the forum.

To everyone pointing to MSDN: You can't be serious. MSDN is near worthless. I use it all the time to get a list of methods and whatnot. But for explaining how things work, ALL Microsoft documentation is absolutely worthless. It's a joke. It's one step up from no documentation at all.

The definition on MSDN for Write(string) is: "Writes the specified string value to the standard output stream." They almost might as well have just left it blank. That "pretty much" says absolutely nothing. But more importantly, it misses the critical difference between Write and WriteLine. First of all, an absolute beginner isn't even going to know what a stream is. Who is this written for? Their documentation is ALWAYS written for those who don't need the documentation. If you can tell everyone off the top of your head what the method does and how it works, then the documentation is written for you. Not that you need it, because you know it off the top of your head. For the people who need the documentation it has practically no useful information whatsoever at all.


Anyway, the primary difference between Write and WriteLine is that WriteLine "wraps" the cursor down to the next line. It has what they call a carriage return and line feed that goes back to the days when computers used punch cards for input and sent ALL of their output to a printer (no such thing as a computer monitor back then). These printers had wheels that pushed the paper forward. So, you had to explicately tell the printer to push the paper forward at the end of each line. This was called a "line feed"(vertically). Then you had to tell the printer to move the print head back to the beginning of the line (horizontally). This was called a "carriage return" with the "carriage" being the print head that returned back to the beginning of the line.

Somehow, this has managed to stick around in computing even today. Some systems will move down to the next line with just one or the other and some still require both the carriage return and the linefeed command to be sent.

I believe you can get the same effect by putting a '\n' in your string in order to send it to the next line (or is it '/n', I forget).

Anyway, the difference between Write and WriteLine is that WriteLine will move down to the next line o the screen when it writes what it's going to write. Write keeps the cursor right at the end of what you write without going down to the next line.

So, you may want to use Write to put something on a line and then another Write to put something else on the same line right after it. But it will never go down to that next line unless it runs off the end of the screen or you do a WriteLine.

In fact, you can do a Console.WriteLine() with no string given just to go down to the next line.

Oh. And that talk about terminators and output streams... an output stream is just where the text is sent to. Normally that's going to be your screen. But it could be a file on the harddrive or other device. The "terminator" is the carriage return and line feed I was telling you about, but for some devices the terminator might be different.

This post has been edited by Curtis Rutland: 25 October 2012 - 11:34 AM

[Ryano121]

Quote

But for explaining how things work, ALL Microsoft documentation is absolutely worthless.

I think you are missing the point here. The documentation shouldn't tell us how everything works, we shouldn't be worried about how it works as long as it does what it should do. That's one of the main purposes of the .Net framework itself - to abstract away underlying complexities so that we can just stick to writing our programs and not worry about whatever is going on behind the scenes.

Quote

The definition on MSDN for Write(string) is: "Writes the specified string value to the standard output stream." They almost might as well have just left it blank. That "pretty much" says absolutely nothing. But more importantly, it misses the critical difference between Write and WriteLine.

But that IS what Console.Write does. It writes the string to the output stream. Nothing more nothing less. If you look at Console.WriteLine however we get

Quote

Writes the specified string value, followed by the current line terminator, to the standard output stream.

Which again is exactly what the method does.

I don't really see what you are complaining about here. Ok the MSDN documentation is far from perfect, but it's still a hell of a lot better than a lot of others out there.

[Curtis Rutland]

Well, I have to completely disagree with you. What page did you land on? Because when I look up Console.Write, I get to this page:

http://msdn.microsof...sole.write.aspx

With a list of all overloads. Let's pick a simple one, the one that takes a string parameter:

http://msdn.microsof...y/hebffx2d.aspx

Yes, the top definition is anemic. That's actually the text used to define it in IntelliSense (via XML comments). If you continue, there's an explanation of parameters, exceptions, a notes section that gives two important pieces of information, an example of how to properly use it, framework version information, and a related links section, which has WriteLine as one of the related links.

Seems like a lot of good information to me. No, it didn't cover the difference between WriteLine in the Write article, but it links to WriteLine, which has its own explanation, and the differences become clear.

I'd be happy to debate this in deeper detail if you'd like, but let's not do it in someone's help thread. If you want, start a topic in the C# advanced discussion area.

Split and moved.

[BBeck]

@Ryano121, I stick to my accusation that Microsoft's documentation is crap. Not only for C#, but everything Microsoft has ever produced. Goodness knows I've read enough of it.

I work exclusively with MS products, so I really couldn't compare it to how others document their products.

But my point is that they could have documented it only in Greek and "technically" that would be documentation. But the fact of the matter is that most of us don't speak or read Greek. So, they might as well not provide documentation at all if they're going to do that.

You should not be required to have a PHD in computer programming in order to begin learning C#. If you're going to the documentation, it's because you don't know about it. That's why you go to the documentation.

I can barely read their definition and I know exactly how it works without even looking it up. What's a "terminator"? Is Governator about to bust in here? And in the Write definition they should have mentioned that it does not include a terminator, because that's "kinda" critical here.

And what's a stream? Forget about output or input stream. What's a stream? There's a river flowing through my computer?!?! Won't that fry the electronics? Sure. You and I know what a stream is. But a beginner who's looking up the definition of Write and WriteLine definately doesn't have the foggiest idea what a stream is. So why bother even writing anything if the people who need the information can't read it?

Crap. Worthless crap I tell you. Bring Steve Balmer in here. I'll say it to his face! ;-)

This post has been edited by BBeck: 25 October 2012 - 11:28 AM

[modi123_1]

Sounds like someone was bitten with the hyperbole bug and getting a little hysterical (or is flat out trolling).

I still disagree with you. The documentation provide is clear. Why would a PhD be required? I hear a ton of claims sans warrants (or even cherry pies).

I've mentored and taught people how to interact with MSDN and once they realized it gave a great signpost for methods, namespaces, and what they do they never groused. Sure complex topics need to have a slightly different lexicon but it isn't some gibberish.

If you are new and do not know what a 'stream' I would think you would investigate that. I mean - certainly file streams, data streams, memory streams, output streams, etc are never ever used ever in .NET... ever.

Quote

cout is an object of class ostream that represents the standard output stream. It corresponds to the cstdio stream stdout.

http://www.cplusplus.../iostream/cout/

Quote

public void print(String s)

Print a string. If the argument is null then the string "null" is printed. Otherwise, the string's characters are converted into bytes according to the platform's default character encoding, and these bytes are written in exactly the manner of the write(int) method

http://docs.oracle.c....lang.String%29

edit.. a few more.

Quote

print evaluates each expression in turn and writes the resulting object to standard output (see below).

http://docs.python.o...tmts.html#print

Quote

putStr :: String -> IO ()Source

Write a string to the standard output device (same as hPutStr stdout).

http://hackage.haske...e.html#v:putStr

Quote

Format is a function in Common Lisp that can produce formatted text and is normally used in a manner analogous to printf in C and other curly bracket programming languages.

https://en.wikipedia...8Common_Lisp%29

Quote

format is useful for producing nicely formatted text, producing good-looking messages, and so on. format can generate and return a string or output to destination.

http://www.lispworks...c/Body/22_c.htm

Quote

print(obj, ...) → nil click to toggle source

Prints each object in turn to $stdout. If the output field separator ($,) is not nil, its contents will appear between each field. If the output record separator ($\</code>) is not nil, it will be appended to the output. If no arguments are given, prints <code>$_. Objects that aren’t strings will be converted by calling their to_s method.

http://www.ruby-doc....#method-i-print

Quote

printf

Format and print data.
Write the formatted arguments to the standard output under the control of the format.

http://ss64.com/bash/printf.html

Quote

Description

WRITE OPERATOR enables an application to write a message to one or more system consoles and, if necessary, wait for a reply. The command can specify route codes. This is of particular use to application packages that need to issue their own operator messages.

http://publib.boulde...iteoperator.htm

This post has been edited by modi123_1: 25 October 2012 - 12:21 PM

[Sergio Tapia]

What documentation would say is good in contrast? Ruby on Rails docs? Shit if you're a newbie. Django, the champion of "Best Docs Ever!" also pretty daft for a newbie.

Documentation shouldn't just be a list of API's. It should also follow a logical, progressive learning course for new developer coming to the ecosystem.

Take for example CakePHP's Cookbook hosted on their site. It gives you a "start here", then here, then here approach. And it's STILL lacking.

[AdamSpeight2008]

MSDN Documentation is equivalent to an Electronic Components Datasheet
It's technical documentation, not a tutorial / walk-through for Software Engineers.
Like the Datasheet provides data and information for Electronics Engineers. Application Notes provide tutorials, guidance and examples, kinda tutorials for software components.


Tutorial: Basic Guide To MSDN

The Visual Studio IDE also provides Code Snippets for VB.net and C# other languages.

You want difficult Documentation try looking for information about COM interfaces and InterOP

This post has been edited by AdamSpeight2008: 25 October 2012 - 02:00 PM

[Curtis Rutland]

modi123_1, on 25 October 2012 - 01:45 PM, said:

Quote

Description

WRITE OPERATOR enables an application to write a message to one or more system consoles and, if necessary, wait for a reply. The command can specify route codes. This is of particular use to application packages that need to issue their own operator messages.

http://publib.boulde...iteoperator.htm

Did you just bust out the CICS API docs? Oh snap!

Actually, the little time I had to spend with IBM's documentation (for writing a WebSphere MQ client in C#) was absolutely miserable. I had to use their Java documentation to find what I needed, then figure out how to do it in C#.

AdamSpeight2008, on 25 October 2012 - 03:31 PM, said:

MSDN Documentation is equivalent to an Electronic Components Datasheet
It's technical documentation, not a tutorial / walk-through for Software Engineers. Like the Datasheet provides data and information for Electronics Engineers.

And IMO, that's what it should be. Documentation isn't meant to be a beginner's tutorial. In fact, that's what tutorials are meant for. Documentation isn't just for newbies; there's no way someone could remember all of the .NET Framework. Even experts use the documentation, for a refresher, or for things they've never worked with before.

So the documentation has a fine line to walk: it has to be friendly enough so that people can actually use it, but have enough information and detail to actually be useful to people.

[AdamSpeight2008]

BBeck, on 25 October 2012 - 06:58 PM, said:

I believe you can get the same effect by putting a '\n' in your string in order to send it to the next line (or is it '/n', I forget).

Assuming it's C#. Also depends on the Environment, hence Environment.NewLine

Quote

Anyway, the difference between Write and WriteLine is that WriteLine will move down to the next line o the screen when it writes what it's going to write. Write keeps the cursor right at the end of what you write without going down to the next line.

A 5 minute throw away / experimental project and you could have discovered it yourself.
Engineers learn for their's and others mistakes. Why did the Tacoma Narrow Bridge Collapse
or NASA's Mars Orbiter Crash?

Quote

Oh. And that talk about terminators and output streams...

If I didn't know the definition of a word, I'd look it up in a Dictionary.

[h4nnib4l]

There is a bit of a learning curve to using MSDN documentation, and I'm mostly just referring to the fact that you need to peruse all the way to the bottom for better descriptions and other "notes" that would be helpful. A while back, I was writing an extension method for the DirectoryInfo() class that would copy its underlying file and folder structure to a target, and needed to copy the ACL. I read up on the GetAccessControl() and SetAccessControl() methods, but couldn't figure out why I couldn't call the "get" on the source and just pass the results to the "set". Had I bothered to read to the bottom of the SetAccessControl() page, to the remarks section, I would have seen it clearly explain that SetAccessControl() only persists FileSecurity objects that have been modified after object creation. That's all the information I needed, but apparently I just expected it to be the first thing I read, which is my fault. As others have said, documentation shouldn't be a tutorial, there are tutorials for that. Documentation is for practitioners to reference; I haven't been doing this for that long, but it generally has everything I need (short of tutorials on concepts, but again, there are tutorials for that).

[no2pencil]

I have plenty of negative things to say about Microsoft. Their MSDN isn't one of them. I've written many programs with great aid of the MSDN.

Not sure what issues you are having with it, but I belive this falls into the "can't make 100% of the people happy 100% of the time" category.

[marty617]

The only complaint I have about Microsoft documentation is the inconsistent inclusion of samples or links to samples on the same page as the description of the class/method. Some pages are very good about that while for others you have to dig a little deeper.

[KYA]

I find it to be hit or miss as well. Something I'd like to see an example for never has one and vice versa.