Thread: iostream article review

  1. #1
    Administrator webmaster's Avatar
    Join Date
    Aug 2001
    Posts
    1,012

    iostream article review

    Manasij has been working on an article series on IO streams and we've been collaboratively editing a document on Google Docs. It's now at a point where it'd be good to get feedback from the wider community. If you're interested in providing feedback, take a look at

    https://docs.google.com/document/d/1.../edit?hl=en_US

    I've set it so that for now, anyone with this link can view or add comments.

  2. #2
    C++まいる!Cをこわせ!
    Join Date
    Oct 2007
    Location
    Inside my computer
    Posts
    24,654
    I'd be careful saying streams support ANSI and Unicode since the standard does not mandate what char and wchar_t is (some implementations may not adhere to ANSI or Unicode). Furthermore, in C++11, we'll get proper unicode types.

    Aside from that, there are two major things.
    First, who is this written for? Newbies? In that case, you may need to review the article to find spots such as "it allowed us to chain" which a newbie often wouldn't understand. What is chaining? How do we accomplish chaining? Why does it work?
    Secondly, I'd rather see a passive writing style rather than active ("here we can chain the operations" vs "the operations can be chained in this way").
    Last edited by Elysia; 09-27-2011 at 05:26 AM.
    Quote Originally Posted by Adak View Post
    io.h certainly IS included in some modern compilers. It is no longer part of the standard for C, but it is nevertheless, included in the very latest Pelles C versions.
    Quote Originally Posted by Salem View Post
    You mean it's included as a crutch to help ancient programmers limp along without them having to relearn too much.

    Outside of your DOS world, your header file is meaningless.

  3. #3
    [](){}(); manasij7479's Avatar
    Join Date
    Feb 2011
    Location
    *nullptr
    Posts
    2,657
    Quote Originally Posted by Elysia View Post
    I'd be careful saying streams support ANSI and Unicode since the standard does not mandate what char and wchar_t is (some implementations may not adhere to ANSI or Unicode). Furthermore, in C++11, we'll get proper unicode types.
    Would remove those terms and just state character and wide character.
    Aside from that, there are two major things.
    First, who is this written for? Newbies? In that case, you may need to review the article to find spots such as "it allowed us to chain" which a newbie often wouldn't understand. What is chaining? How do we accomplish chaining? Why does it work?
    For ++newbie !

    Secondly, I'd rather see a passive writing style rather than active ("here we can chain the operations" vs "the operations can be chained in this way").
    Err.. Point out some .. where it looks too awkward.

  4. #4
    C++まいる!Cをこわせ!
    Join Date
    Oct 2007
    Location
    Inside my computer
    Posts
    24,654
    It's not about too awkward. It's about you having chosen the style of active form (ie, I did this and this) instead of passive form (ie, this was done and then that).

    Example:
    Active form: The streams we are talking about here, are designed to fit almost any data-handling purpose imaginable.
    Passive form: The streams being discussed here, are designed to fit almost any data-handling purpose imaginable.

    There are also some words that almost sound like taboo, such as "imaginable." Doesn't sound very professional. Consider reforming sentences to:
    The streams being discussed here, are designed to fit many data-handling purposes.

    But don't worry about rewriting the entire article. Just keep it in mind for future articles. Some people prefer this style.
    Quote Originally Posted by Adak View Post
    io.h certainly IS included in some modern compilers. It is no longer part of the standard for C, but it is nevertheless, included in the very latest Pelles C versions.
    Quote Originally Posted by Salem View Post
    You mean it's included as a crutch to help ancient programmers limp along without them having to relearn too much.

    Outside of your DOS world, your header file is meaningless.

  5. #5
    Devil's Advocate SlyMaelstrom's Avatar
    Join Date
    May 2004
    Location
    Out of scope
    Posts
    4,079
    You keep explaining things as if to say "Wikipedia does not exist."

    Anyway, the page appears to be down for me at work, so I didn't get a chance to read it... but I would comment that Elysia first example of using the passive voice would be correct. An article that intends to explain a component of a programming language should keep the language as the subject and not the reader. On the other hand, if the article was about how to program then I would put the user in the subject. That said, as I have not read it, I can't say how often the writer is using the active voice, so I don't know how critical it is.
    Last edited by SlyMaelstrom; 09-27-2011 at 08:02 AM.
    Sent from my iPadŽ

  6. #6
    Registered User Codeplug's Avatar
    Join Date
    Mar 2003
    Posts
    4,981
    Here is some info on character sets: CodeGuru Forums - View Single Post - ConvertStringToBSTR lost char
    Things aren't as "implementation defined" in C++11.

    Also keep in mind that:
    Code:
    ofstream file1("foo1");
    file1 << 123;
    
    wofstream file2("foo2");
    file2 << 123;
    Both files will be identical. Each file will hold a stream of "char" types, which are encoded based on the locale associated with the streams. In the second case, the wide stream is converted to a narrow stream before being writing to the file. This seemed to be a point of confusion in the comment stream.

    gg

  7. #7
    spurious conceit MK27's Avatar
    Join Date
    Jul 2008
    Location
    segmentation fault
    Posts
    8,300
    The "passive" vs. "active" criticism is highly subjective. In general, I prefer a passive style, but not as an absolute rule. In English, there is nothing syntactically wrong with an active style and if that is what comes naturally to you, you might as well stick with it. Good quality writing done in an active voice is much nicer to read than bad quality writing in a passive voice. IMO many people are clearer when they use the active voice, and easily slide into incomprehensibility when they try to use the passive voice. WRT to technical documentation, I would rather read something that makes obvious sense in a "clunky" active voice rather than something ambiguous in a "less clunky" passive voice.

    For example:
    Streams natively work with standard data types, but streams also let you design your own classes so that you can use the same I/O system.
    Is very clear, reads fine, and is in an active voice. If it ain't broke, don't fix it. I can almost promise you will go from clear to confusing, and concise to long-winded.

    A few corrections I would make:

    Page 1

    The streams we are talking about here, are designed to fit almost any data-handling purpose imaginable.
    Loose the red bits.

    The type of the character normal characters (char) or wide characters (wchar_t).
    This sentence is missing a verb.

    Page 2

    Once you are familiar with element of the design contains and how to apply those concepts to design a robust I/O system for your software, an undestanding of what belongs where in the hierarchy will come naturally.
    Understanding is mis-spelled, and the bit in bold needs fixing (maybe "the elements the design contains"?). I'd actually re-think or just remove the whole sentence.

    You have to get the input characters into a recognizable data-type for it to be of any use other than a character array.
    "other than as a character array."

    Apart from that, it allows you almost limitless freedom to manipulate those streams using both Object Oriented interfaces and working directly on character buffers when necessary.
    should be both using

    Page 4

    First, the stream is initialized with the appropriate type of values (like a std::string for a stringstream and the filename for an fstream) and suitable modes (like
    How about: "the stream is initialized using the appropriate type (...) and suitable modes set".

    Page 5

    Once you’ve at the right location in the stream,
    Once you've what?

    Handling Errors gracefully is often an important thing to do for building a robust system.
    "to do for" should be "to do when". Subjectively, I'd loose the "often".

    The ‘errors’ or ‘signals’(eg: reaching the end of the file) in this case are generally when a stream encounters something it didn’t expect to.
    Lose the "to" at the end. Maybe "are generally when" might be better as "generally occur when".

    The status of the stream can be obtained from the individual bits of the respective iostate object, but using the bool functions provided for that purpose makes it easier.
    The good(), bad(), fail() and eof() functions provide information about the state and the clear() is used to reset the stream and clear the error.
    "it" should be "this". lose "the".

    Page 9

    They allow you a lot of control about the exact way how you want to read a value from the stream into the given variable
    Bold bit should be "exactly how" or just "the exact way".

    an approach when combined with these streams that can lead to excellent, straightforward designs.
    Should be "an approach which when combined". Lose "these" and "that". Probably then commas after which and streams to isolate the phrase more clearly. Subjectively, I'd replace "excellent" with "nice" or "clean".

    Page 10
    This seemingly simple task would have taken at least 30 lines of code or more without such facilities.
    Not a grammatical point, but a logical one: the comparison is contrived since you are operating on a stringstream. You cannot operate on a C++ stringstream without these facilities, in any number of lines. But if the stringstream is supposed to represent a method or a data source, and if by "without such facilities" you mean "using vanilla C", the task is equally simple, 5-10 lines at most. If you mean something completely else, such as "using python" or "using a hatbox", you are just being silly.
    Last edited by MK27; 09-27-2011 at 09:35 AM.
    C programming resources:
    GNU C Function and Macro Index -- glibc reference manual
    The C Book -- nice online learner guide
    Current ISO draft standard
    CCAN -- new CPAN like open source library repository
    3 (different) GNU debugger tutorials: #1 -- #2 -- #3
    cpwiki -- our wiki on sourceforge

  8. #8
    [](){}(); manasij7479's Avatar
    Join Date
    Feb 2011
    Location
    *nullptr
    Posts
    2,657
    Quote Originally Posted by SlyMaelstrom View Post
    You keep explaining things as if to say "Wikipedia does not exist.".
    What do you mean by that ?

  9. #9
    [](){}(); manasij7479's Avatar
    Join Date
    Feb 2011
    Location
    *nullptr
    Posts
    2,657
    @MK27 : Thanks.
    Some of the grammatical mistakes appeared because of combining parts of sentences of an earlier revision, now redundant .
    The rest, I was not aware of.

    Also, I removed the sentence of " .....at least 30 lines of code or more without such facilities. " as it was 'somewhat' foolish.
    But I'm curious about how you could do it in about 5 lines in C ?

  10. #10
    C++ Witch laserlight's Avatar
    Join Date
    Oct 2003
    Location
    Singapore
    Posts
    28,412
    Quote Originally Posted by manasij7479
    But I'm curious about how you could do it in about 5 lines in C ?
    What task is that again?
    Quote Originally Posted by Bjarne Stroustrup (2000-10-14)
    I get maybe two dozen requests for help with some sort of programming or design problem every day. Most have more sense than to send me hundreds of lines of code. If they do, I ask them to find the smallest example that exhibits the problem and send me that. Mostly, they then find the error themselves. "Finding the smallest program that demonstrates the error" is a powerful debugging tool.
    Look up a C++ Reference and learn How To Ask Questions The Smart Way

  11. #11
    [](){}(); manasij7479's Avatar
    Join Date
    Feb 2011
    Location
    *nullptr
    Posts
    2,657
    Quote Originally Posted by laserlight View Post
    What task is that again?
    Extract an unknown precision double from a known starting position within a string.
    Compute its square.
    Put the square back.(The length of the square may vary )
    Last edited by manasij7479; 09-27-2011 at 10:33 AM.

  12. #12
    spurious conceit MK27's Avatar
    Join Date
    Jul 2008
    Location
    segmentation fault
    Posts
    8,300
    Quote Originally Posted by manasij7479 View Post
    But I'm curious about how you could do it in about 5 lines in C ?
    Again, this is contrived because it begs the question, "what are you actually trying to do, besides just operate on a C++ stringstream"? In order to come up with a realistic alternative, the purpose of the string stream is needed.

    So I did something that I think sticks closely to what you did. I replaced <stringstream> with <cstdio>, commented out 7 lines in main and added 6.

    Obviously, this is a bit silly: if you are working in C++, you might as well use C++ features, but I think it does demonstrate that the task you use as an example is no simpler or easier in C++ than it is in C (so the place this would require "at least 30 lines" is...mythical):

    Code:
    #include<iostream>
    //#include<sstream>
    #include <cstdio>
    
    using namespace std;
    
    int main()
    {
    
    //    stringstream my_stream(ios::in|ios::out);
        std::string dat("Hey, I have a double : 74.79 .");
    
    //    my_stream.str(dat);
    //    my_stream.seekg(-7,ios::end);
    	const char *str = dat.c_str();
    	int len = dat.length() - 7;
    	str += len;
    
        double val;
    //    my_stream>>val;
    	sscanf(str, "%lf", &val);
    
        val = val*val;
    
    //    my_stream.seekp(-7,ios::end);
    //    my_stream<<val;
    //    std::string new_val = my_stream.str();
        char new_val[len+64];
        sprintf(new_val, "%s%.2lf", dat.substr(0, len).c_str(), val);
    
        cout<<new_val;
    
        return 0;
    }
    Output:

    Hey, I have a double : 5593.54
    Last edited by MK27; 09-27-2011 at 11:01 AM.
    C programming resources:
    GNU C Function and Macro Index -- glibc reference manual
    The C Book -- nice online learner guide
    Current ISO draft standard
    CCAN -- new CPAN like open source library repository
    3 (different) GNU debugger tutorials: #1 -- #2 -- #3
    cpwiki -- our wiki on sourceforge

  13. #13
    C++まいる!Cをこわせ!
    Join Date
    Oct 2007
    Location
    Inside my computer
    Posts
    24,654
    Quote Originally Posted by MK27 View Post
    The "passive" vs. "active" criticism is highly subjective. In general, I prefer a passive style, but not as an absolute rule. In English, there is nothing syntactically wrong with an active style and if that is what comes naturally to you, you might as well stick with it. Good quality writing done in an active voice is much nicer to read than bad quality writing in a passive voice. IMO many people are clearer when they use the active voice, and easily slide into incomprehensibility when they try to use the passive voice. WRT to technical documentation, I would rather read something that makes obvious sense in a "clunky" active voice rather than something ambiguous in a "less clunky" passive voice.
    It is true that it is debatable and subjective, but I just want to point out that some prefer the passive voice alternative. I've yet to hear anyone (well, aside from students) who prefer active over passive. There are also those who dislike active.
    All in all, learning how to write in passive style is a good skill™.
    Quote Originally Posted by Adak View Post
    io.h certainly IS included in some modern compilers. It is no longer part of the standard for C, but it is nevertheless, included in the very latest Pelles C versions.
    Quote Originally Posted by Salem View Post
    You mean it's included as a crutch to help ancient programmers limp along without them having to relearn too much.

    Outside of your DOS world, your header file is meaningless.

  14. #14
    Registered User
    Join Date
    Jun 2005
    Posts
    6,815
    Quote Originally Posted by Elysia View Post
    Example:
    Active form: The streams we are talking about here, are designed to fit almost any data-handling purpose imaginable.
    Passive form: The streams being discussed here, are designed to fit almost any data-handling purpose imaginable.
    Just to be picky, your examples are both (colloquial or conversational) passive forms. The difference is that the first example is in first person form, and the second is impersonal.

    Either way, I don't like those styles of wording ... both beat around the bush.

    It is not even necessary to say the article is discussing these things - that is a statement of the self-evident, since it is!

    Try a wording like "The streams are designed to support any type of data handling".

    Note that my comments are without context of the article: I don't have access (no google account) so can't comment further.
    Right 98% of the time, and don't care about the other 3%.

    If I seem grumpy or unhelpful in reply to you, or tell you you need to demonstrate more effort before you can expect help, it is likely you deserve it. Suck it up, Buttercup, and read this, this, and this before posting again.

  15. #15
    C++まいる!Cをこわせ!
    Join Date
    Oct 2007
    Location
    Inside my computer
    Posts
    24,654
    Well, introducing yourself in any way or form, be that as was written or by the use of a pronoun such as "I" is not a good way to write these articles if you want to go the "passive" way.
    By wording it as "The streams we are talking about here" gives the impression that the writer is trying to say something, as often used in speech, but the second way is often more used in writing (stating facts) and that is more to the point I wanted to make an example of.
    Meh. I'm not a linguistic expert, so I don't know if what I am typing here is 100% correct. I am just a little experienced in writing so-called passive form and is my preferred style for writing any type of article. I'm trying to convey that way with examples, but I don't know if the terms used to describe those examples are 100% correct.
    Quote Originally Posted by Adak View Post
    io.h certainly IS included in some modern compilers. It is no longer part of the standard for C, but it is nevertheless, included in the very latest Pelles C versions.
    Quote Originally Posted by Salem View Post
    You mean it's included as a crutch to help ancient programmers limp along without them having to relearn too much.

    Outside of your DOS world, your header file is meaningless.

Popular pages Recent additions subscribe to a feed

Similar Threads

  1. Article in GDM about DarkBasic PRO
    By jasonkidd05 in forum Game Programming
    Replies: 5
    Last Post: 02-03-2008, 04:47 AM
  2. Article
    By crvenkapa in forum A Brief History of Cprogramming.com
    Replies: 1
    Last Post: 05-15-2007, 01:23 AM
  3. critique this article
    By kermit in forum A Brief History of Cprogramming.com
    Replies: 10
    Last Post: 10-13-2004, 08:28 PM
  4. Article in GDM about DarkBasic PRO
    By DavidP in forum A Brief History of Cprogramming.com
    Replies: 2
    Last Post: 09-03-2003, 06:27 PM