Jump to content
  • Advertisement
Sign in to follow this  
freeworld

do you ever go back and clean up your files? and were do you comment?

This topic is 2710 days old which is more than the 365 day threshold we allow for new replies. Please post a new topic.

If you intended to correct an error in the post then please contact us.

Recommended Posts

just curious as I was about to do this very thing. I'm knee deep in the middle of a project and been having to hack alot together just to get my portion up and running for others to use. despite the fact that I over comment I found myself searching through my own code for 20 minutes just to figure out which function I was supposed to use and track down were I was setting a random parameter. I realized that I'm a little ahead of were I need to be right now, so I decided to go through a couple source/header files and clean up the coded so it's a little easier to read.

Does anyone else do this regularly or at all?

also what is the (corporate) preferred place to put comments. Do you comment the header file and not the source file or viceversa? I like putting my comments mostly in the header file and only loosely comment major sections of the source file. ie


/** Header */

void MyFunction(); /** this function does this, this is what the parameters are suspected to be... ie r should be 0 - 1 */




I always place my comments at the end of the function declaration and on the same line, but I have a large monitor so I can see the whole line, the guy I'm working with gets on my case about it all the time cause he can't see the whole comment without scrolling.

Share this post


Link to post
Share on other sites
Advertisement
I usually comment behind the function declaration in my header files, too.

// This function does absolutely nothing!
void complex_function(std::string heystring); // I dunno what this does
void new_function(); // This function does absolutely nothing!

If i remember it, I copy the comment above each function inside the implementation file.

// This function does absolutely nothing!
void new_function()
{
}

When i do multiline comments, i have this weird idea to keep them aesthetically pleasing:

/*
* This is a lovely multiline comment (Monospaced beauty!)
* ----------------------------------------------------------
* and this is a brief description of a module,
* placed in a header file.
* # Todo:
* + Add random stuff.
* * Clean previous stuff.
* - Remove obsolete functions.
*/

- I put them in the top of my header files. They may take up around 25 lines and contain a title, a short description and
major features of the module, -as well as a crappy todo-list which i never update.

I rarely use multiline comments, unless i remove something temporarily, or if i need to explain an advanced function in implementation file.

Basically i only document really advanced algorithms, or hacks, or stuff that could otherwise be difficult to understand later.

... That's what I do.... :-/

Share this post


Link to post
Share on other sites
I do this quite frequently. Once something is working it is much easier to see better ways for the code work. When implementing new things I try pretty hard to keep it clean but it is easy to do some quick hacks to get it working.

This extra time spent perfecting working code can save a lot of time in the future when you are extending the code.

Share this post


Link to post
Share on other sites
Maybe you could benefit from looking at an automatic documentation generation tool, for example Doxygen. Even if you don't generate the documentation, it can help you create a good and consistent style for your comments and it forces you (well, sort of) to consistently document what you are doing, making it easier to find the right class or function later.

Personally, I find it easiest to grog code if it is split up into small logical units of functionality. Therefore I have many rather small files, most of them only with a single class with a single purpose. That way I can easily find that if I need functionality X then I need class X located in X.h and X.cpp. Large files with code for many different purposes are detrimental to understanding code and to code reuse, in my view.

Share this post


Link to post
Share on other sites
I probably spend about a third of my coding time on cleanup and documentation. I have a very heavily iterative development style, where I'll bang out something, get it to work, then refine it and slowly improve it until I'm happy with the results. A lot of bugfixes (especially under deadline) never get cleaned up, but they do at least get documented clearly.

IMHO consistent and disciplined cleanup of code is essential for maintaining a good code base. Without it, you're liable to get lost in the weeds pretty easily.

As for commenting, I generally have a comment at the top of each file, briefly explaining its purpose, and a comment above each function definition in the source explaining how it works, any interesting things that might need to be known by the caller, and so forth. Any arcane or bizarre code gets heavily commented in-line.

You can see examples of my style in the Epoch programming language if you're curious :-)

Share this post


Link to post
Share on other sites
I don't personally comment my own code at all, as a solo developer. I never have. Because I try very hard to adhere to things like single responsibility, separate functions instead of deep nesting and the use of magic numbers (just examples), I have never gone back over old code and not been able to understand it as quickly by reading the code as I would have by reading comments.

Just personal preference I guess. Whatever works for you.

In terms of libraries, I much prefer separate documentation to commented code. You don't tend to start opening up Win API headers as a reference, you go to MSDN.

Where libraries are free and the makers don't have the time to produce documentation, for example Box2D, I personally find it a real chore to tinker around in the source, reading comments to find out how things work. This is not a complaint as with a free library you don't expect the developers to invest the time in documentation, but for me the fact remains that well written, complete and separate documentation like MSDN is far easier to use.

Share this post


Link to post
Share on other sites
Yes, I do both every time I touch the code.


When I start, I add comments to everything that I didn't instantly understand, or rename it so it doesn't require the comments. This will (hopefully) help the next person who comes through.

Then I remove code that is no longer relevant, and merge code that can be merged. Test and verify, then submit to version control.

Then I make my changes. I add comments to anything that I think might be confusing. Then I test, verify, and submit.

Then I clean up again, removing and merging whatever I can. Test and verify. Submit the code to version control, and be done.



If you don't take time to clean up the code EVERY TIME you use it, the code will quickly become a cluttered mess. Garbage will accumulate. Program performance will suffer, and programmer productivity will suffer. Nobody will be happy. Then people will want to throw the whole thing out and start over.

I comment directly in the source to anything that requires explanation and cannot be given a self-explanatory name. External documentation is rarely viewed and quickly obsolete. Put comments where they improve understanding, and remove them when they are no longer accurate.

Doing the little tasks before and after is necessary every time you modify code. Think of it as checking the equipment before use (e.g. oiling and dusting as necessary), making your change, and then cleaning up the dust and debris after the task is done.

Share this post


Link to post
Share on other sites
Wherever possible it should be obvious WHAT a function does from its prototype. If you can't get across what it does from its prototype without having a ridiculously long name, then perhaps the function needs to be split up or redesigned. State the assumptions and preconditions a method may have, but remember that not all functions have preconditions or make assumptions worth nothing.

The most important thing to comment is WHY something does what it does, or why it does it in a certain way. One can figure out what a function does given sufficient time, but given all the time in the world one can not always figure out why it does what it does.

Also of high importance is WHERE things come from (constants, algorithms). I frequently put http links in my code to any useful sources of pertinent information.

Depending on how likely it is that a function will need to change, and how large it is, it may also be good to describe HOW it works.

Share this post


Link to post
Share on other sites
I always comment as I write. The idea of never commenting your own code strikes me as silly, and opens the very real risk that you're going to come back to some code in 6 months time and not have the foggiest idea what it's doing or why you did it that way.

I agree totally with iMalc - the purpose of comments is to give yourself (or anyone else reading your code) information that may not be totally obvious from just the code itself. You often see beginning programmers getting the wrong idea about comments and missing this point.

A bad comment goes something like this:
i++; // add 1 to i
A good comment goes something like this:
x /= i; // we guaranteed that i is non-zero when loading (see the LoadStuff function) so we don't need to worry about division by zero

Always remember that reading code is harder than writing code, and comment with this in mind. It's a skill you'll need to learn, but if you ever do need to go back to some old code you'll be grateful that you did.

Share this post


Link to post
Share on other sites
I do pretty much the same as the OP.

In my header files I usually comment short discriptions over my functions using /** ... */:
class SceneRenderer_ToSwapchain: public SceneRenderer
{
public:
SceneRenderer_ToSwapchain(void);
~SceneRenderer_ToSwapchain(void);

/** Create your buffer resources here */
// SizeX, Y = Size of the rendertargets (0 will get the size of the HWND)
// TargetWindow = Hint for renderers using a swapchain
virtual HRESULT CreateBuffers(UINT SizeX, UINT SizeY, SharedParameters* SharedParams, HWND TargetWindow=NULL);

/** Called when the buffers need to be resized */
virtual HRESULT ResizeBuffers(UINT SizeX, UINT SizeY);

/** Delete the objects you've created in CreateBuffers() here */
virtual HRESULT DeleteBuffers();

/** Prepare yourself for the following world render (Set targets, etc) and
call the renderfunction of the Scene passed in. */
virtual HRESULT RenderScene(Scene* Scene);
//...


IMHO using /** ... */ for those function declerations looks much pretier than //. I use // in my funcitons, though.

Also of high importance is WHERE things come from (constants, algorithms). I frequently put http links in my code to any useful sources of pertinent information.[/quote]

I don't know if it's good or not, but I like to put the names of the classes where a constant is used in front of them. Goes like this (For the class WBaseLightComponent):
const D3DXVECTOR4 WBASELIGHTCOMPONENT_LINE_COLOR = D3DXVECTOR4(0.5, 0.5, 1, 0.5);

Don't know if that is a good practice or not. Is anyone doing so as well?

Share this post


Link to post
Share on other sites
Sign in to follow this  

  • Advertisement
×

Important Information

By using GameDev.net, you agree to our community Guidelines, Terms of Use, and Privacy Policy.

Participate in the game development conversation and more when you create an account on GameDev.net!

Sign me up!