c (++) was not designed to be structured, it is simple and fast to write. look at delphi (pascal) or asm, these are very readble languages. perhaps you may adapt some of their concepts (have a look at the delphi-vcl code, even as non-pascal-programmer you will see its meaning at a glance)

AND PLEASE, USE A BLANK AFTER EVERY COMMATA!!! BUT NOT AFTER OR BEFORE BRACKETS !!!!!!!!

That''s sorta what I do. The "//////" do a great job of seperating comments from code.... when done right:

    ///////////////////////////////////////////////////////////////////--------------------------Example.cpp------------------------////                                                             //// created by: Me                                              //// created on: 9.27.00                                         ////                                                             //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////---------------------------Includes--------------------------//#include <windows.h>//---------------------------Defines---------------------------//#define WINDOW 600/////////////////////////////////////////////////////////////////    

like that.

==============================
\\// live long and prosper; \||/ die short and rot.
==============================

I don''t use /////''s for making boxes, I much prefer:

    /**************************************************** *                   Name of Function               * *     What this function does, what params it takes* *     and what it returns                          * ****************************************************/    

I think that looks neater. I only have comments in boxes before functions or when it is hard to understand what a line is doing. For example:

if(num & 0x8000000)num = (~num)+1; // get the absolute value 

------------------------------
#pragma twice

sharewaregames.20m.com

Hmmm... there are too many comments in that bit of code that are useless. It is a somewhat good way of having clean and readable code but you don''t need to comment as much as you did for your code to be readable...



Cyberdrek
Headhunter Soft
DLC Multimedia

Ugh, comment boxes should be a no-no =). Code Complete actually talks about comment boxes and how they shouldn''t be used because they are so much of a pain to maintain. Leaving the ending spaces and asterisk out looks just as good, but makes it SO much easier to change the comment.


- Houdini

personally, my coding usually doesn''t have many comments (not a good thing, i hear), but when I do comment, I put the longer explanations of, say, functions or the program title head, in an asterix box like furby, then for explanations of single lines, i just do a few tabs at the end of the line and write a comment with the double-slash.

Ex:

        /**************************************************** *  Example.cpp -- An example program               * *  Created by Falden                               * *  27-09-00                                        * ****************************************************/#include <iostream.h>  // includes the Streaming I/O fileint main(){    cout << "Hello!!"; // displays ''Hello!!'' to the screen    return 0;          // returns 0}    

to me, that''s just easier to read than all the // all over the place, but I think that finding a universal comment style that everybody likes is impossible, so just find what you feel comfortable with and stick to it.

of course, this is all just answering a part of the question of ''what is a good coding style'', but to that I give the same answer: find what you feel comfortable with and stick to it.

Ick, there is some foo-foo code on this thread.

I lean towards heavy commenting, but try to keep it from being too distracting without spending too much time thinking about it.

multiple #includes on a single line = yick!

Commenting is important, but you should *not* comment every line of code.
Doing something like:

    cout << "Hello!!";	// Displays "Hello!!" to the screenreturn 0;		// Returns 0      

is complete overkill. If whoever reads the code doesn't instantly realize what those lines of code does without reading the comment then they have *no business whatsoever* reading the source.

Comment lines of code only if it is not immediately apparent what it does, as overdone commenting makes it difficult to see at a glance which pieces of code are trivial, and which are not.
That aside, it is often good practice to comment the use and functionality of functions and methods at the start of it's definition.

Personally I like using the JavaDoc method of commenting, but unfortunately I haven't found a JavaDoc-style comment-extractor for C++-code. Anybody know of one?

-Neophyte

Edited by - Neophyte on September 28, 2000 4:52:22 AM

Neophyte, I 100% agree. I cringe when I see stuff like that. I lean more towards commenting on the function level and giving an overview of what each function does more than how they do it. As you pointed out, that should be easy to figure out by reading the code.