Friday, October 5, 2007

Comments Alongside Code (CAC)

While working on a game I’m currently developing I started to think about how poor some text editors really are. I usually stick with Visual Studio as my preferred environment and it’s a very powerful IDE. But one thing I’m currently missing is the ability to treat any certain range of characters across different lines as a group of text.

Allow me to explain. Back in the old days, any terminal had a fixed number of characters one could display on a single line (typically 72) and basically because of this; you limited any single line to that number of characters. While we still try to avoid writing long lines of code (for readability purposes) we tend to use more characters per line now a days and it’s more a question of what’s suitable rather than what’s readable. I tend to average 80 or 100 characters per line and the readability is still great. But with my screen resolution I can fit up to 148 characters per line and thus wasting about 50 characters, for something which I believe, can be put to better use.

Any modern text editors worth mentioning have a way of doing syntax highlighting (colors to certain keywords or expressions) most text editors also do code folding or outlining which is a way of grouping lines together (this requires some sort of semantic awareness). But I have yet not seen a text editor which can take any rectangular selection as a group of text. I think this is best illustrated by an example.

// A Direct 3D device object other than the one that returned this code caused the 
// hardware adapter to be reset by the OS. Delete all video memory objects (surfaces, 
// textures, state blocks) and call Reset() to return the device to a default state. 
printf( "IDirect3DDevice9::Present D3DERR_DEVICELOST\n" );
One can for instance write comments preceding a certain action which is very common and not wrong in any way at all. But what about writing comments like this:
g_Globals.BeginD3DDReset(); // NOTE to self: this is blocking. 
                            // Blocking the game loop becuase the graphics device
                            // is currently unavailable will totally mess up the
                            // fixed game updates, just ignore the rendering step
                            // until the device is successfully reset.

This is not ideal all the time but this way of writing a comment will allow me to write comments alongside code and I think that rather useful. For this to be really practical, I would expect a text editor to recognize the above comment as comments alongside code (CAC) and conveniently indent the whole thing if any code following the above statement exceed current indentation (see below). It should also adjust the input mode so that these whitespaces used to align the comments alongside code never interfere with the actual writing of additional code. One way to think of this, is to picture the text as a layer on top of your code. This layer, is directly synonymous with the actual text itself and is just a feature by the text editor for positioning comments alongside code.

g_Globals.BeginD3DDReset();             // NOTE to self: this is blocking. 
                                        // Blocking the game loop becuase the graphics device
DoMoreCode( NULL, NULL, NULL, NULL );   // is currently unavailable will totally mess up the
                                        // fixed game updates, just ignore the rendering step
                                        // until the device is successfully reset.

One additional thing which came to mind while writing this is that manual word wrapping is a tedious task. That being said, any implementation of comments alongside code should have the ability to word wrap a comment group through a simple user action. The idea is to augment the experience while still working with text files and never adding any clutter to the actual code. Whitespaces can thus not be considered clutter but storing information about a comment block inside the actual comment would be considered clutter. However, it would also be useful as it could provide sensible metadata about the comment itself. E.g. one could chose to treat a comment beginning with a certain word or pattern as a certain marker.

I think it’s obvious at this point why this would be a very useful and powerful feature. Not only as an extension but it could theoretically provide a lot more functionality than just comments alongside code when working with plain text files.

Hopefully I will be able to revisit this topic with a working demo sometime in the future but I leave no such promises.

To all you Emacs and VIM users, if you think you got it, then you're wrong. I use VIM myself and VIM does not do what I want to do. You can do rectangular text selection, but the editor needs to recognize the comments as more than just comments. It a block which needs to adjust to it's surroundings.


thoward37 said...

Try using the Alt key when selecting. That will give you a square selection area. Then to move it around, jut grab the selected square and put it where you want. It works like what you're talking about. It takes a minute to get used to, but you can move that kind of block comment around very easily that way.

John said...

Neat, that I did not know. Thanks!

Now there's still the issue with this being manual labor but as far as VS goes that's one more additional point to take note of.

I'd love it if right-aligned comments or CACs as I call them would adjust indent if I started to write code to the left of the comment.

Anonymous said...

Once you get into some real hard core professional work you'll realize comments are rare :)

John said...

I suppose you're right about that. A lot code is generally self explanatory, especially if you're very good at it.

This CAC idea is just a nice way to include comments in your code. It might encourage even the most hardcore to write more comments as the comments themselves don't run with the code, instead they go alongside with the code.