Thread: Fixing the Indentation draft

  1. #1
    C++まいる!Cをこわせ!
    Join Date
    Oct 2007
    Location
    Inside my computer
    Posts
    24,653

    Fixing the Indentation draft

    OK, so let's try to fix this thing so we can actually merge the two articles.
    First, I'll list Mario's suggestion's first, as best I can:

    Suggestion #1
    You can't advertise "choose one, be consistent" but then advocate just one style throughout your article. It's one thing to write code, it's another to write code to demonstrate how you should indent. In that context it is definitely best to take the opportunity to show the reader different formating styles. Not just one.
    Suggestion #2
    People don't really need to be taught how to indent. They know how to operate the tab key. They understand the visual significance of properly indenting code as soon as you explain it to them in one or two paragraphs and give some examples. It's a darn damn easy concept to grasp! More so because they experience indenting concepts it even before having any kind of programming education. They did it all the time at school ranging from math class to accounting and physics. They even do it all the time when adding bulleted lists to a word document. They need instead to be directed towards concepts such as "why is it important", "choose your own, be consistent", and "here's a few different indenting styles".
    Suggestion #3
    You can't force people to choices. You can't for instance tell them they should use tabs instead of spaces, or they should only do indent+1 at every new level. Those that don't agree with you, are coming from a programming background, and are just now learning C/C++, will strongly disregard and reject your whole article. They know better that indenting is mostly about taste and they will take you for a newbie because you don't advertise that.
    Suggestion #4
    Never ever treat your readers as being stupid! When I started in programming your were probably not even born, I'll take offense. Conversely, when you started programming your lack of knowledge didn't make you stupid. It made you smart.
    Suggestion #5
    Finally, an article is not going to save the world. No matter how well it is written, you will never achieve any visible results. Keep that in mind when writing them and especially when being so draconian about such simple issues as indentation.
    As to these, my current draft at least addresses complaint number 3. I have tried to rewrite it be neutral in ways of coding styles, explaining that they are a good thing and that programmers should try to adopt to their own style. Then it goes on to recommend coding style practices which makes the code more readable.
    I also revised the code a little to remove some examples that seemed to "silly," as in perhaps they were making the readers look dumb. I don't think the rest are so low, though. I always like examples because they make your point go across. It's much easier to see an example after reading to actually understand what the heck it's on about.

    For complaint nr 1, I have rewritten the code not to promote one coding style, and although the article uses the allman coding style, it does show examples using the "4 big" styles as listed on the page linked to me some time ago. I don't know if I can be clearer than that? Might mixing coding styles actually be a good thing in here? I don't know if using one coding style in one example and another in another might be such a good idea...

    As for complaint 2... well, some do not understand indentation properly, and even seeing and understanding what it is, they don't actually understand how to do it so that it looks good, which is why I've opted to put out some guidelines of general coding styles.

    And as for complaint 5, I can only say that teaching people to indent properly helps them as they help us. Maybe it should be seen as "strict" as it should be, but merely more like a suggestion. I'm trying to change my posts so it looks a little more that way nowmore. But I still believe indentation and coding styles are important, and they make it so much easier for me, and probably others, too, who actually reads the code others post.
    I've seen some big messy code and some very clean, nice code. And I do prefer the clean code. I wish everyone could write such clean code. And I will continue to suggest, and to try, to make people at least try to write such beautiful, clean code. Programming is an art, after all.

    Any critiques, suggestions or complains are, of course, welcome. And examples of where there are problems helps big time. And if there would also be an example of what to change the text into, that would help even more.
    Let's all make this work so we can close this issue, shall we?

    Link to draft, for those who don't know:
    http://cpwiki.sf.net/User:Elysia/Indentation
    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.

  2. #2
    Just Lurking Dave_Sinkula's Avatar
    Join Date
    Oct 2002
    Posts
    5,005
    How about adding a link, or separate entry + link, to code beautifiers. Pick your style of choice and beautify regularly!
    7. It is easier to write an incorrect program than understand a correct one.
    40. There are two ways to write error-free programs; only the third one works.*

  3. #3
    C++まいる!Cをこわせ!
    Join Date
    Oct 2007
    Location
    Inside my computer
    Posts
    24,653
    Might just do that. Thanks for the heads up!
    Will add to a TODO.
    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.

  4. #4
    Lurking whiteflags's Avatar
    Join Date
    Apr 2006
    Location
    United States
    Posts
    9,611
    As for complaint 2... well, some do not understand indentation properly, and even seeing and understanding what it is, they don't actually understand how to do it so that it looks good, which is why I've opted to put out some guidelines of general coding styles.
    As I've tried to explain to you though, and I'm not sure if you've listened to me when I've wrote this before, most of the code we see has other problems. I'm pretty sure that most of the issues are caused because people don't know how to program yet. Planning is a part of it, and it's often neglected, at least initially, in most students' assignments. I think this causes a majority of the problems that you see. Some posters here give me the impression that they're designing and writing their homework at the same time.

    Not that that's the wrong way initially. Speaking from personal experience, most of the time I was simply put to the task of fixing something that almost worked. As a student, my time was spent working as a debugger. If I had indentation problems it was usually because I didn't understand language concepts and their syntax; I was more worried about fixing it and fixing it now. Most people level out after some experience That's why Dave's suggestion is a good one! People need to understand what their tools do for them, as well as the language before indentation sort of expertly flows out of them.

    Consistency is the message that your article doesn't emphasize, and I think you ignore some of the other reasons that poor indentation can happen. Teaching people how to make broke stuff look nice is kind of a waste of time. We can't expect new programmers to know everything, true. But it would insult intelligence to say that programmers can't learn how to, or even prefer, to indent themselves. There should be a difference between "what the article should say" and "how to help posters," and what role the article plays on the forum. On a per-situation basis, it would be appropriate for the poster to say something more I think. Peplies like, "Learn some indentation: http:// ..." are often off-topic and incomplete, especially if the OP asked a decent question.

    That is most of the problem I think. Writing a thorough tutorial is always something that I've been very vocal against. despite your claims that the only complaints you've ever recieved is how it's written.
    Last edited by whiteflags; 02-19-2008 at 04:46 PM.

  5. #5
    (?<!re)tired Mario F.'s Avatar
    Join Date
    May 2006
    Location
    Ireland
    Posts
    8,446
    Quote Originally Posted by Elysia View Post
    And I will continue to suggest, and to try, to make people at least try to write such beautiful, clean code. Programming is an art, after all.
    It sure is an art if you look at it as a creative process. However, I find no romance in cleanly indented code. Instead, I find it in simple and elegant code.

    I honestly don't care if code is presented to me - and it has many times throughout my professional life - poorly indented. Contrary to you I don't make a flag out of that. I may advise against it on occasion, but don't use it a measure in order to determine the quality of the code.

    My C++ experience is limited to just a couple of years. But I have learned enough of it, and seen enough code, to know its no different from any other programming languages I worked on. Reading poorly indented code is an exercise you better get used to, because it will follow you in case you decide to make programming your career.

    As people evolve in their knowledge of the programming language, they themselves start to see the benefits of that and many other so-called good practices. And its not your article, or anyone else's article that will soon bring them enlightenment. It will be their experience.

    And that is why I say that being overly descriptive in such an issue as indentation only brings noise and adds nothing to the learning process of the reader other than a general feeling of you preaching him. You won't get any more results. A simple, to the point and generic article will bring just the same results and will be easier to read.

    You want people to read your article, not give up half-way because it's boring them like daddy does sometimes.
    Last edited by Mario F.; 02-19-2008 at 06:22 PM.
    Originally Posted by brewbuck:
    Reimplementing a large system in another language to get a 25% performance boost is nonsense. It would be cheaper to just get a computer which is 25% faster.

  6. #6
    Lurking whiteflags's Avatar
    Join Date
    Apr 2006
    Location
    United States
    Posts
    9,611
    As people may see momentarilly:
    Quote Originally Posted by Brace placement
    Some languages, such has Python or Haskell, rely on whitespace expressly to delimit their statement blocks ("forced indentation"), but most languages do not use indentation this way. In C, C++, and C# the curly braces are used by the compiler to delimit the beginning and the end of functions and other statement blocks, such as if or while. Formatting your braces consistently is generally only an aid to human readers: most will agree good style is any format which allows a programmer with working knowledge "eyeball" statements associated with those constructs.
    So, it's not perfect; mostly perpetually going to be in a bit of a technical nit. Hopefully now the article is intellectually honest than the initial version. Perhaps even Elysia finds this more helpful than before.

  7. #7
    & the hat of GPL slaying Thantos's Avatar
    Join Date
    Sep 2001
    Posts
    5,681
    Forgive me if I missed it somewhere else but:
    1) Why the heck is this topic here?
    2) Why are you trying to do something so futile?

  8. #8
    C++まいる!Cをこわせ!
    Join Date
    Oct 2007
    Location
    Inside my computer
    Posts
    24,653
    Quote Originally Posted by Thantos View Post
    1) Why the heck is this topic here?
    Because there are two indentation articles on the wiki and everyone agrees they must be merged. But they cannot be merged just yet, which is why we have the problem.

    2) Why are you trying to do something so futile?
    Futile indeed? Well, call it whatever, but I'm still going to go through the trouble of doing it so I don't have to explain it later.
    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.

  9. #9
    (?<!re)tired Mario F.'s Avatar
    Join Date
    May 2006
    Location
    Ireland
    Posts
    8,446
    Quote Originally Posted by Elysia View Post
    Futile indeed? Well, call it whatever, but I'm still going to go through the trouble of doing it so I don't have to explain it later.
    Go ahead if it suits your fancy. As I said numerous times it's a subject not worth a tenth of the discussion it has gathered. So, really it's time I give up. Nevertheless I hope you realize that after you finish, your article may be edited by the community.

    It's a wiki wicked world.
    Originally Posted by brewbuck:
    Reimplementing a large system in another language to get a 25% performance boost is nonsense. It would be cheaper to just get a computer which is 25% faster.

  10. #10
    & the hat of GPL slaying Thantos's Avatar
    Join Date
    Sep 2001
    Posts
    5,681
    Quote Originally Posted by Elysia View Post
    Because there are two indentation articles on the wiki and everyone agrees they must be merged. But they cannot be merged just yet, which is why we have the problem.
    Doesn't explain why this topic is HERE and not at the wiki. The wiki's I've been to have discussion pages for the articles.

  11. #11
    (?<!re)tired Mario F.'s Avatar
    Join Date
    May 2006
    Location
    Ireland
    Posts
    8,446
    Quote Originally Posted by Thantos View Post
    Doesn't explain why this topic is HERE and not at the wiki. The wiki's I've been to have discussion pages for the articles.
    The CPWiki (Cprogramming Wiki, if you will) is experiencing constant timeouts, connection resets, and being generally a hard place to work on. Myself, I gave up on publishing content for a while until sf.net does whatever it needs to do to improve performance on that server.

    It was then agreed, any discussion could be done here on the general forum since it would be, at the very least, less annoying than having them over there.
    Originally Posted by brewbuck:
    Reimplementing a large system in another language to get a 25% performance boost is nonsense. It would be cheaper to just get a computer which is 25% faster.

  12. #12
    C++まいる!Cをこわせ!
    Join Date
    Oct 2007
    Location
    Inside my computer
    Posts
    24,653
    Quote Originally Posted by Mario F. View Post
    Go ahead if it suits your fancy. As I said numerous times it's a subject not worth a tenth of the discussion it has gathered. So, really it's time I give up. Nevertheless I hope you realize that after you finish, your article may be edited by the community.

    It's a wiki wicked world.
    It is. But the main point was that if it explains something or helps in any way, then I'm for it.
    Of course anyone may edit it, but I don't think it will be like last time. No major overhauls without a lot of discussion. If it was, then we'd have a communication problem. As you say, it's a community project.

    Quote Originally Posted by Mario F. View Post
    The CPWiki (Cprogramming Wiki, if you will) is experiencing constant timeouts, connection resets, and being generally a hard place to work on. Myself, I gave up on publishing content for a while until sf.net does whatever it needs to do to improve performance on that server.

    It was then agreed, any discussion could be done here on the general forum since it would be, at the very least, less annoying than having them over there.
    Not to mention, many seem blissfully unaware that they exist and many do not participate in them and discussion on the forum is 3x better because you can quote, it separates replies, you can get email notifications, it looks better, etc.
    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.

  13. #13
    Lurking whiteflags's Avatar
    Join Date
    Apr 2006
    Location
    United States
    Posts
    9,611
    It's been a few days and you have yet to attempt to integrate your article with the community one.
    ]It is. But the main point was that if it explains something or helps in any way, then I'm for it.
    Of course anyone may edit it, but I don't think it will be like last time. No major overhauls without a lot of discussion. If it was, then we'd have a communication problem. As you say, it's a community project.
    It annoys me that you're using "community" as some sort of brand name for your ideas. Despite any agreement, you continue to link your own pages around as if the community article did not exist. If this becomes commonplace, then there really is no point in having a wikipedia for the site. The articles available become the loosely affiliated, decentralized opinion of a few key individuals (especially that of the so-called "goddess" who basks in her own hype) instead of a group concensus. At least I initially acknowledged your contribution, yet you refuse to extend the same courtesy to the community article.

    I can only assume that you honestly think the community article does nothing of value and should be deleted. If that is the discussion at hand, than you as an individual shouldn't reserve the right to speak for everyone involved in the wiki project, either. If it has to become an all-or-nothing deal, then get on with it please, and let the owners trash the subject.

  14. #14
    C++まいる!Cをこわせ!
    Join Date
    Oct 2007
    Location
    Inside my computer
    Posts
    24,653
    Quote Originally Posted by citizen View Post
    It's been a few days and you have yet to attempt to integrate your article with the community one.
    Yes, and I've had like 3-4 hours at most at home and most if it I've spent looking around the forum.

    It annoys me that you're using "community" as some sort of brand name for your ideas.
    I don't, whatever you may think.

    Despite any agreement, you continue to link your own pages around as if the community article did not exist.
    And as I've already stated, the community article is not sufficient.

    ...(especially that of the so-called "goddess" who basks in her own hype)...
    The user title mean nothing. It is not directed at who I am nor anything else of the type. It is simply a title; nothing more, nothing less.

    At least I initially acknowledged your contribution, yet you refuse to extend the same courtesy to the community article.
    And I believe I've already stated my opinions on that one. It's too much Wikipeda-esque. Too little tutorials or rich contents. It offers mostly explanations on what things are but never how to fix them.

    I can only assume that you honestly think the community article does nothing of value and should be deleted. If that is the discussion at hand, than you as an individual shouldn't reserve the right to speak for everyone involved in the wiki project, either. If it has to become an all-or-nothing deal, then get on with it please, and let the owners trash the subject.
    That is my belief since I do not consider it adequate enough. However, I will not do something dastardly and delete the whole thing. It has a right to exist on its own. I do not find it of much use, however.


    Having looked over all replies, I have yet to see any concrete help on how to make the article better, save for the ones I already have. Yet, no examples, or sections of text that can be changed from X to Y to demonstrate your point. It helps, you know.
    The debate seems to be over whether it's worth it. OK listen, I'm going to reveal my reasons here.
    Someone comes with poor indentation in code. Maybe void main. Maybe implicit main. Maybe reading strings with scanf. They are such small, yet subtle problems. And we try to teach them to not do it. Which is to say, why is indentation different? Why not try to teach newbies as much as we can, to share our experience? Linking to the main indentation article does not help, because I'm pretty sure they'll still have problems indenting. That's where my draft comes in. It's rich in description of good coding style rules (though it explicitly also mentions that they aren't rules; they are more like guidelines). So they can actually read that and understand. So we don't have to teach everything every time. That is why we have a wiki!
    So whether or not it's worth the time, whether or it's important, it's just an article to link to to make sure newbies get the grasp of indentation a little better. Without us having to explain every single thing. That's what we wanted in the first place.
    Last edited by Elysia; 02-21-2008 at 03:00 PM.
    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.

  15. #15
    Lurking whiteflags's Avatar
    Join Date
    Apr 2006
    Location
    United States
    Posts
    9,611
    Please do not play cookie cutter with my replies.
    Despite any agreement, you continue to link your own pages around as if the community article did not exist. If this becomes commonplace, then there really is no point in having a wikipedia for the site. The articles available become the loosely affiliated, decentralized opinion of a few key individuals (especially that of the so-called "goddess" who basks in her own hype) instead of a group concensus.
    There is no sense in having a wikipedia if there can not be any group concensus over such a stupid issue. That confirms your belief it is perfectly okay to just ignore the community regarding any issue at all, and use it as a platform for your own ideas when people disagree with you. Until we have a public article based upon mutual agreement the subject at hand deserves not to be covered.

    Publish your thoughts somewhere else if you are too lazy to take matters into your own hands and fix what's already been written in the community article. I'm urging you to take laserlight's advice. How about you merge it somehow, and then let the interested parties react. I'm sure that we are all smart enough to write something to everyone's satisfaction. It won't kill you to critically review your article, anyway; through revision, you may find a clearer, concise way to help individuals through the main article.

    I agree that the main article has shortcomings. For example, the examples section is particularly thin, but I didn't want to judge it myself, because it really hung on how effective the text communicated the idea. After all, as long as the text was understood, the difference between poorly indented and well-indented is obvious; the benefits, obvious.

    If you want to teach people the point-of-view of an experienced person, than take a sample program such as this:
    Code:
    #include <string.h>
    #include <stdio.h>
    #include <stdlib.h>
    
    void process_file ( char * longOrderID, size_t bufsiz, FILE * file );
    
    int
    main ( int argc, char * argv[] )
    {
        if ( argc == 2 ) {
            char longOrderID[BUFSIZ];
            FILE * fin;
    
            fin = fopen( argv[1], "r" );
            if ( fin != NULL ) {
                process_file( longOrderID, sizeof longOrderID, fin );
                puts( longOrderID );
                fclose( fin );
            } else {
                perror( argv[1] );
            }
        } else {
            puts( "incorrect number of arguments--provide a file to read" );
        }
        return 0;
    }
    
    void
    process_file ( char * longOrderID, size_t bufsiz, FILE * file )
    {
        char * p = longOrderID;  /** position in longOrderID **/
        char * nl = NULL;        /** find newlines **/
    
        size_t read;
    
        strcpy( p, "Value=" );
        read = strlen( p );
        p += read;
        bufsiz -= read;
    
        /** read in chunks: **/
        while ( bufsiz > 0 && fgets( p, ( int )bufsiz, file ) != NULL ) {
            if ( ( nl = strchr( p, '\n' ) ) != NULL )
                *nl = '\0';
    
            strcat( p, "," );
            read = strlen( p );
            p += read;
            bufsiz -= read;
        }
    }
    And use it as the visual aid to explain as you see fit: refer to line numbers like they do in books if you must. I'd use the principles set forth in the community article.

    You probably have structural changes you'd like to see; you're free to make them. I just don't want the neutrality of the article completely destroyed. The code above is as well indented if it were written like Whitesmith's, where your paltry "+1 indentation level" rule doesn't exist. The brace placement you suggest is not applicable, because the brace is in the same character row as any statement in the block. You have to be sure that the principles you espouse are in the right place, and expand beyond what is "simple," because oversimplifying is intellectually dishonest.
    Last edited by whiteflags; 02-21-2008 at 03:32 PM.

Popular pages Recent additions subscribe to a feed

Similar Threads

  1. Replies: 3
    Last Post: 05-23-2009, 06:20 PM
  2. Indentation in Code::Blocks
    By PING in forum Tech Board
    Replies: 8
    Last Post: 03-26-2008, 03:33 PM
  3. setting indentation in dev-c++
    By richdb in forum A Brief History of Cprogramming.com
    Replies: 8
    Last Post: 06-12-2006, 08:03 PM
  4. Fixing my (Stupid) IE Menubar
    By civix in forum Tech Board
    Replies: 2
    Last Post: 01-04-2004, 02:22 AM
  5. Fixing Laptops
    By zdude in forum Tech Board
    Replies: 5
    Last Post: 06-16-2003, 01:56 AM