Thread: Dreaded Code Style Argument

  1. #1
    Grammar Police HybridM's Avatar
    Join Date
    Jan 2003
    Posts
    355

    Dreaded Code Style Argument

    Hey fellas,

    I was just having a look at this article on flipcode.com about coding style.

    here is the link:
    http://www.flipcode.com/articles/art...ingstyle.shtml

    Everything the guy does seems sound to me, except for a couple of things.
    He's extremely comment happy it seems to me. I can see the infinite advantages in well documented code, however I would much prefer to read/write a seperate documentation to accompany the code. This guy's code gets bloated VERY quickly.

    Secondly, the opening curly bracket. A lot of people seem to use this style (same line) but to me it seems much nicer to have it on the next line, what's the argument for using this same-line style?

    Lastly I have an actual question, I'm sure I've read about this before, but what does a const return type do for a function? Anything exciting?
    Thor's self help tip:
    Maybe a neighbor is tossing leaf clippings on your lawn, looking at your woman, or harboring desires regarding your longboat. You enslave his children, set his house on fire. He shall not bother you again.

    OS: Windows XP
    Compiler: MSVC

  2. #2
    Registered User
    Join Date
    Feb 2003
    Posts
    76
    Its a good thing to be comment happy. Just think if you have a program hat you created a few months ago, and you decide to update. If you didn't have comments then you would not have a clue whats happening. belive me I have done it and now I comment just as much as any guy.
    The open brace thing is just a matter of style with C++ there is no right way of doing things. I personally agree with you about having the brace on the next line. The only time I don't is when im doing a quick one line function.
    The const return type I have only come across when using pointers it makes sure that the pointer can't be altered in any way. In other word if it points to an int then it will always do so. Just the same as if you place it after the function name. Im sure you have heard this before but its good programming practice.

  3. #3
    It's full of stars adrianxw's Avatar
    Join Date
    Aug 2001
    Posts
    4,829
    Having the opening brace on the same line is an old fashioned style. It arose in the days when we all used character mode terminals which only displayed 24 lines of text. You could see more of the code on the screen using this style.

    Many people still hang on to this style despite studies which show Allman format has the greatest readability and fewest "first glance" errors.
    Wave upon wave of demented avengers march cheerfully out of obscurity unto the dream.

  4. #4
    *******argv[] - hu? darksaidin's Avatar
    Join Date
    Jul 2003
    Posts
    314
    Despite those "studies" I prefer to have the opening bracket on the same line. I don't know who "Allman" is and frankly, I don't really care what some people think is readable and what not. To me, having the opening bracket on the same line is a lot easier to read.

    As for this piece of code found in Hybrid's link....

    Code:
    	public:
    
    		/**
    		 * Get the speed of the car
    		 *
    		 * @return speed in miles per hour.
    		 */
    		const float getSpeed();
    
    		/**
    		 * Set the speed of the car
    		 *
    		 * @param pSpeed new speed of the car.
    		 */
    		void setSpeed(const float pSpeed);
    ...

    I think it's definetly not something I could "show my mama". It's overloaded with comments. It's like not finding the wood because of all the trees.

    I try not to use any comments "in" the code unless its a comment about an entire code-block. I prefer to have comments about a single function like the above ones behind the function, starting at column 60 if possible.

    btw, how do you wrap long parameterlists ? Like this ?

    Code:
    // use glu to build mipmaps
    gluBuild2DMipmaps(
      GL_TEXTURE_2D,
      oImage.iChannelCount,			// must be 3 or 4, 4 for RGBA mode
      oImage.iSizeX,
      oImage.iSizeY,
      iTexMode,				// rgb or rgba textures
      GL_UNSIGNED_BYTE,			// subpixel datatype
      oImage.pbData
    );
    Thats how I normally do it and it's analog to the way I use the curly brackets.

  5. #5
    Registered User
    Join Date
    Apr 2003
    Posts
    2,663
    what does a const return type do for a function? Anything exciting?

    If you do something like this, I don't think it has any meaning:
    Code:
    const int func(void)
    {
        const int sum = 10;
        return sum;
    }
    ...because you are passing by value in the return statement, and therefore a copy of sum is made and the copy is returned. Since a copy cannot modify the original, the compiler doesn't care what you do with the return value. (I don't know how the original being destroyed when the function returns fits into the story--it might be the whole story.)

    But, if you have something like this:

    const int* func(void)

    then you aren't allowed to do this:

    int* pint = func();

    because you might try this:

    *pint = another_value;

    and that would violate the constantness of the int "pointed to by the pointer" that the function returned--which is extremely exciting stuff.
    Last edited by 7stud; 08-23-2003 at 07:00 AM.

  6. #6
    Registered User
    Join Date
    May 2003
    Posts
    1,619
    Using const for a copied return type is useless.

    Those comments such as these, though:

    Code:
    	public:
    
    		/**
    		 * Get the speed of the car
    		 *
    		 * @return speed in miles per hour.
    		 */
    		const float getSpeed();
    
    		/**
    		 * Set the speed of the car
    		 *
    		 * @param pSpeed new speed of the car.
    		 */
    		void setSpeed(const float pSpeed);
    can be useful; there are a lot of automatic documentation-generation programs that can make HTML or some other form of documentation from comments like these; I imagine that may be his purpose. I see this a lot on projects I work on; it makes maintaining the documentation, especially in the presence of multiple developers making changes, much easier.

    I do not comment my code as heavily as he does. I remember I had a CS professor who once said "If your code needs a lot of comments to understand it, then delete it and write clearer code."

    I also use the "old style" of open braces on the same line, just because I've been programming for ages and that's just how I've always done things. Once you're used to it, it's as easy to read.
    Last edited by Cat; 08-23-2003 at 08:22 AM.

  7. #7
    Toaster Zach L.'s Avatar
    Join Date
    Aug 2001
    Posts
    2,686
    As Cat said, especially with the '@' character and the format of those particular lines, it is for the automatic documentation tools. His code inside the functions themselves I disagree with. If you have code which is complex, or subtle, then it definitely should be well commented. Comments like this:

    // Create a pointer to an int storing age.
    int* pAge;

    Are useless (in my opinion), however. First, the line of code says exactly the same thing that the comment does, and if you changed something (type, etc.) then the comment would go from useless to detrimental unless you made sure to update it as well. If there are fewer comments (placed as needed in complex code), then they are much more likely to be updated when something changes.
    The word rap as it applies to music is the result of a peculiar phonological rule which has stripped the word of its initial voiceless velar stop.

  8. #8
    Registered User
    Join Date
    May 2003
    Posts
    1,619
    I played around a bit with doxygen, the documentation program he uses -- it's quite good, actually, I plan to use it on any large project or anywhere I think I will be reusing code.

Popular pages Recent additions subscribe to a feed

Similar Threads

  1. Clean Code...
    By Devil Panther in forum C Programming
    Replies: 24
    Last Post: 07-16-2005, 01:50 AM
  2. Nested loop frustration
    By caroundw5h in forum C Programming
    Replies: 14
    Last Post: 03-15-2004, 09:45 PM
  3. True ASM vs. Fake ASM ????
    By DavidP in forum A Brief History of Cprogramming.com
    Replies: 7
    Last Post: 04-02-2003, 04:28 AM
  4. Seems like correct code, but results are not right...
    By OmniMirror in forum C Programming
    Replies: 4
    Last Post: 02-13-2003, 01:33 PM
  5. Interface Question
    By smog890 in forum C Programming
    Replies: 11
    Last Post: 06-03-2002, 05:06 PM