Commenting

[Eleventeen]

I'm a big fan of it, I use it all the time. All you have to do is write some code then write what it does by using comments.

	
	// Pixel format descriptions. Didn't know there was such a thing up to now.
	static PIXELFORMATDESCRIPTOR pixelFormatDesc =
	{
		sizeof(PIXELFORMATDESCRIPTOR), 1, // The size of the descriptor and the version of it.
		PFD_DRAW_TO_WINDOW | PFD_SUPPORT_OPENGL | PFD_DOUBLEBUFFER, // Flags.
		PFD_TYPE_RGBA, bits, // The pixel type and bits.
		0, 0, 0, 0, 0, 0, 0, 0, // Red bits, red shift, blue bits, blue shift, green bits, green shift, alpha bits and alpha shift.
		0, 0, 0, 0, 0, // Bits, green bits, blue bits and alpha bits. All for the accumulation.
		16, // The depth bits.
		0, 0, // Stencil bits and the number of auxiliary buffers, which is stupid since on MSDN it says they're unsupported.
		PFD_MAIN_PLANE, // Layer type. Which is ignored, says MSDN.
		0, 0, 0, 0 // Reserved planes, layer masks (ignored, says MSDN), the visible mask and the now ignored damage mask.
	};

/**
 @file COSLayerWin32.h
**/

#ifndef _JE2D_COSLAYERWIN32_H_
#define _JE2D_COSLAYERWIN32_H_

#include <IDefine.h>
#include "COSLayerStub.h"

#include <windows.h>
#include <gl\gl.h>

namespace JE2D
{
	namespace OS
	{
		//! The OS layer for Windows.
		/**
		 COSLayerWin32 is the OS layer
		 for Windows. It generally tracks
		 input and handles putting little
		 itty bitty pixels on the screen.
		**/
		class COSLayerWin32
			: public virtual COSLayerStub
		{
			public:
				//! Constructs the OS layer.
				/**
				 When we create the OS layer, we prevent
				 odd things happening by setting values to default.
				**/
				COSLayerWin32(CEngineLayer* engine, OSLayerProperties* properties)
					: COSLayerStub(engine, properties), renderingContext(0), deviceContext(0),
					windowHandle(0), active(true), startTime(timeGetTime()), lastTime(0),
					time(startTime), frameCap(0)
				{
				}
				
				//! Deconstructs the OS layer.
				/**
				 When we constructed the OS layer we created
				 a window, so now we need to remove that and
				 clean up anything left over.
				**/
				virtual ~COSLayerWin32(void);
				
				//! Starts the OS layer.
				/**
				 This does everything we should've done in the constructer,
				 but returns an error in case we screw up.
				 @return Returns true if there was an error.
				**/
				virtual bool init(void);
				
				//temp until reciever
				static LRESULT CALLBACK windowProc(HWND windowHandle, UINT intMessage, WPARAM wideParam, LPARAM longParam);
				
				//! Runs a loop of the OS layer.
				/**
				 When we run a loop of the layer, we
				 draw everything and update the time.
				 @return Returns true if the OS layer died.
				**/
				virtual bool run(void);
				
				//! Sets the window title.
				/**
				 Windows allows us to set the window title,
				 so you can use this to do it.
				**/
				virtual void setWindowTitle(char* title);
				
				//! Sets if the cursor is visible.
				/**
				 Windows allows us to set if the cursor is invisble,
				 so you can use this to do it. Since we can either be
				 windowed or fullscreen, we have two different options.
				**/
				virtual void setCursorVisible(bool visibleWindowed, bool visibleFullscreen);
			
			private:
				//! Creates a window.
				/**
				 Create and register the windowfor Windows.
				 We can specify the title of the window,
				 the width, the height, bits and whether
				 the cursor is visible when it's windowed
				 or when it's fullscreen.
				 
				 @param title The window title.
				 @param width The width of the window.
				 @param height The height of the window.
				 @param bits The number of bits it should use.
				 @param fullscreen Should it be fullscreen?
				 @return Returns true if any errors occured.
				**/
				bool createWindow(char* title, int width, int height, int bits, bool cursorVisibleWindowed, bool cursorVisibleFullscreen);
				
				//! Remove the window.
				/**
				 We need to remove the window when we deconstruct,
				 so this unregisters the window and OpenGL.
				 @return Returns true if any errors occured.
				**/
				bool removeWindow(void);
				
				//! Draws the frame.
				/**
				 When we run the layer, we need to draw the frame
				 using this private function.
				**/
				void drawFrame(void);
				
				HGLRC renderingContext; ///< The rendering context.
				HDC deviceContext; ///< The device context.
				HWND windowHandle; ///< The window handle.
				HINSTANCE instance; ///< The instance.
				bool active; ///< Is the window active?
				
				double startTime; ///< The time we created the layer.
				double lastTime; ///< The last time we drew a frame.
				double time; ///< The current OS time.
				
				int frameCap; ///< The frame cap.
		};
		
		//! Creates an OS layer.
		/**
		 When we need to create an OS layer, we use this.
		 Partly because it's convenient and partly because
		 we need to return a null pointer in case we had
		 an error creating it.
		 
		 @param engine A pointer to the engine.
		 @param properties The OS properties in a OSLayerProperties struct.
		 @return Returns a pointer to the layer or 0 if it failed to be created.
		**/
		COSLayerStub* createOSLayer(CEngineLayer* engine, OSLayerProperties* properties);
	}
}

#endif

The first is an example of commenting and the second is showing a documented header file.

Who else likes commenting?

[blankthemuffin]

Why not What.

[Xeon06]

Sometimes I feel like the above examples, but most of the time I just comment weird stuff I might not remember later on.

[Nev]

When I first started programming, I thought comments were for losers. I regret that statement even to this day.

[Ortzinator]

Your code should be self-explanatory. The only comments you have should answer "why" not "what".

[compwhizii]

I should really be commenting on my code more than I do.

$counts = mysql_query("SELECT * FROM `count` WHERE `uid` = '".$mod['id']."'");
    while ($count = mysql_fetch_array($counts)) {
        foreach ($count as $k => $v ) {
            if (in_array($k, $events_array)) {
                // What the fuck
                $total[$k] = $total[$k] + $v;
            }
        }
    }

I'm not gonna know what that does in a few days.

Or I'm just really sleepy. I don't care give me dumbs.

[jivemasta]

Commenting every line kills readability and time. You shouldn't need to comment on every little thing because you should be able to just look at the code and tell what you are doing.

Well named variables and members tell way more than comments in most cases. The only time you really need comments is when you have a bug, hack or todo. And that's only to remind yourself to fix something, or to let another team member know what's going on.

If on a team project, commenting can be a little more liberal since you have multiple people working on one thing and some things might need explaining. But even then, your code should speak for itself.

[Eleventeen]

How is explaining arguments over the edge and documenting header files properly bad?

[blankthemuffin]

[QUOTE=Eleventeen;16494598]How is explaining arguments over the edge and documenting header files properly bad?[/QUOTE]

It's not intrinsically bad, you're just repeating yourself over and over again, not helping anybody.

For example, from your code:

[cpp]
//! Creates a window.
/**
Create and register the windowfor Windows.
We can specify the title of the window,
the width, the height, bits and whether
the cursor is visible when it's windowed
or when it's fullscreen.

@param title The window title.
@param width The width of the window.
@param height The height of the window.
@param bits The number of bits it should use.
@param fullscreen Should it be fullscreen?
@return Returns true if any errors occured.
**/
bool createWindow(char* title, int width, int height, int bits, bool cursorVisibleWindowed, bool cursorVisibleFullscreen);
[/cpp]

Really, is any of that crap needed? Look at the function definition. What's it called? "createWindow"? You sure it needs a comment saying it creates a window?

"@param title The window title." NO WAY!?
"@param fullscreen Should it be fullscreen?" Oh I thought that param was asking me if I wanted decaf.

Also you're returning a bool to describe error state? Considering you're not passing any kind of error data back it's hardly a robust system. It's not the C tradition of error codes and it's not c++ exceptions - it's neigh on worthless.

[Pj The Dj]

I don't use comments to talk to myself

Actually somebody else summed it up better, why not what.

[PvtCupcakes]

Anyone actually use a documentation generator like doxygen or javadoc?

[gparent]

[quote]//! Deconstructs the OS layer.
/**
When we constructed the OS layer we created
a window, so now we need to remove that and
clean up anything left over.
**/
virtual ~COSLayerWin32(void);
[/quote]

Way too verbose. This gem from VALVe corporation is more appropriate:

[quote]
//-----------------------------------------------------------------------------
// Purpose: If you don't know what a destructor is by now, you are probably going to get fired
//-----------------------------------------------------------------------------
[/quote]

[HubmaN]

[QUOTE=gparent;16499038]Way too verbose. This gem from VALVe corporation is more appropriate:[/QUOTE]

Was that written before Wikipedia?

[r4nk_]

[QUOTE=PvtCupcakes;16498910]Anyone actually use a documentation generator like doxygen or javadoc?[/QUOTE]

I use doxy for big projects

[gparent]

[QUOTE=HubmaN;16499074]Was that written before Wikipedia?[/QUOTE]

The Source engine has been in production since the past 30 years, of course it was before Wikipedia!

[Jallen]

[QUOTE=Ortzinator;16494220]Your code should be self-explanatory. The only comments you have should answer "why" not "what".[/QUOTE]

I agree in general, but if it's something like an example application, something others will learn from, or something which others will be viewing who have very little understanding of it, then I think commenting "what" isn't a bad idea.

[gparent]

[QUOTE=Jallen;16499500]I agree in general, but if it's something like an example application, something others will learn from, or something which others will be viewing who have very little understanding of it, then I think commenting "what" isn't a bad idea.[/QUOTE]
Problem is, you're confusing code comments with internal documentation. You should document how your code works in a separate document that explains it in greater details. This is why VALVe has an internal wiki, for instance. However, you should not clutter your code with such internal details. Somebody might just be grepping through your code to fix something, and the last thing they need is several pages of comments explaining how to generate a a tachyon beam to invert the z-depth buffer proton matrix.

EDIT: Of course, I'm talking about the "or something which others will be viewing who have very little understanding of it," part. Example applications should be thoroughly commented, but keep in mind that some programmers in your very own team could have a little understanding of the part of the code you're writing on.

[nullsquared]

Your commenting is worthless. Hate to burst your bubble.

[editline]11:33AM[/editline]

Comments aren't for translating your code into English. They're made for describing how something works, like algorithms, etc.

Bad comments:

// create a window titled "title" and return it
window *createWindow(const string &title);

Good comments:

// we need a properties window to allow the client to edit the various
// properties of the currently selected object, such as position and rotation
window *propertiesWin = createWindow("properties");

[editline]11:33AM[/editline]

In fact your commenting isn't just worthless, it makes your code plain annoying to read.

[editline]11:35AM[/editline]

[quote]

                                HGLRC renderingContext; ///< The rendering context.
				HDC deviceContext; ///< The device context.
				HWND windowHandle; ///< The window handle.

[/quote]
:bang:

[compwhizii]

//@todo: These are also useful

[SteveS]

I do comment the occasional thing, just in case I need to remember what it does or for the benefit of someone I'm working with.

A comment like:
printf( "Hello world" ); // prints hello world to console

is dumb.

[Chandler]

sometimes it's necessary in the given context to be overly verbose.

[cpp]
unsigned short screenHeight; // The rendering instance's height. Does not refer to physical screen height.
unsigned short screenWidth; // The rendering instance's width. See above.
[/cpp]

If you can have multiple instances being rendered all at once then it's a good thing to know that screenheight has NOTHING to do with the actual resolution of the application or screen, but refers to one single instance of a rendering "screen"

[gparent]

You can do that by naming the variable properly, though, aka: "ushort renderScreenH;", or variables of that.

If you're in a "RenderWindow" class, then it should be self explanatory also.

[Chandler]

[QUOTE=gparent;16503218]You can do that by naming the variable properly, though, aka: "ushort renderScreenH;", or variables of that.

If you're in a "RenderWindow" class, then it should be self explanatory also.[/QUOTE]

Can't use RenderWindow if you're using SFML's RenderWindow class. It already has a RenderWindow. Although RenderInstance would be fine.

[nullsquared]

[QUOTE=Chandler;16503201]it's a good thing to know that screenheight has NOTHING to do with the actual resolution of the application or screen, but refers to one single instance of a rendering "screen"[/QUOTE]

[cpp]
class screen
{
private:

unsigned _width, _height;

public:

...

unsigned width() const { return _width; }
unsigned height() const { return _height; }
};
[/cpp]

Why would you call it screenW and screenH if it's not "THE" screenW and screenH, but rather an instance's width/height?

[Squad]

[QUOTE=Nevec;16494179]When I first started programming, I thought comments were for losers. I regret that statement even to this day.[/QUOTE]

Isn't it fun going back to a program that when you wrote you thought "Oh this stuff is easy I don't need to comment" only to read it later and go "What the hell was I doing?"

[gparent]

[QUOTE=Chandler;16503556]Can't use RenderWindow if you're using SFML's RenderWindow class. It already has a RenderWindow. Although RenderInstance would be fine.[/QUOTE]

RenderWindow would be fine, because C++ has these things called namespaces. But either way, it was an example.

[Z_guy]

[QUOTE=Squad;16504024]Isn't it fun going back to a program that when you wrote you thought "Oh this stuff is easy I don't need to comment" only to read it later and go "What the hell was I doing?"[/QUOTE]

I love doing that, but I usually go "What the hell was I thinking?!?!".

[Squad]

[QUOTE=Z_guy;16505569]I love doing that, but I usually go "What the hell was I thinking?!?!".[/QUOTE]

The worst is when you have to work on a program someone else wrote who can't comment.

Someone made a program for a cosmetology program and I had to fix it for them because they added some stuff or changed something around and the program didn't work for them.

So I open up the code that the previous user wrote and he had variables named X, Y, F, H, G...

He had functions like

function ReDrawWindowwithImages()
***BUNCH OF STUPID CODE****
end

with the comment of

// ReDrawWindowwithImages function.

[Loli]

/**
@file COSLayerWin32.h
**/

Don't use this. To optimise your code us

//
//@file COSLayerWin32.h
//

[ROBO_DONUT]

I don't usually do more than TODOs and FIXMEs in program code.
I write a little more in headers.

If something is really counter-intuitive, I'll usually make a small note.