Do you comment your code?

In these sorts of discussion there's usually someone terminally smug who says "I write the comments first, and then the code afterwards". These are the people who, as children, wrote all their thank-you letters on Christmas Day, and before starting to play with the presents.

Personally, I do comment my code in some detail, but I go back and do most of it at the end (or at a major milestone). As a general rule - which, of course, I fail to live up to all the time - I won't deliver code to a client if I'd be unhappy about that code being published on a forum such as this, or if the code couldn't readily be maintained by someone else reasonably proficient in whatever environment. For something like an EA I also usually provide separate documentation confirming what the EA does and why, what the parameters do and how they interact, what considerations need to be taken into account, and what external factors such as broker issues can potentially cause problems etc. For personal use, I'll write myself much, much scrappier notes along the same lines.

As far as I'm concerned, code quality goes hand in hand with something else: avoiding excessively "clever" and compressed code unless there's a reason such as a major speed advantage in a scenario where it actually matters. I came across something delightful on this subject recently: "Fixing code is twice as hard as writing it in the first place. Therefore, if you write some code which you think is really clever and elegant and concise, you are by definition too stupid to fix it."

Finally, code comments are like any literature in that they're an act of communication, with one or more people. The comments in your code don't have an empirical, measurable quality any more than a novel does. It depends on the reader. You can write 5 lines of comment for every line of code, but a developer who's smarter than you and more proficient than you may still be baffled if they're naturally approaching the problem from a different angle. Really good comments need to explain "why" as well as "what", but I've never seen a discussion of code comments where the examples put forward as best practice don't assume that "everyone thinks like me". And I'm as guilty of this as everyone else.

When I started life 25 years ago as an Assembler programmer, it was cool not to comment code at all.

Now, for me, it depends upon the purpose of the project.

If I'm going to share the source MQ4, then I'll document fully.

If I plan only to share the EX4, and its a simple EA, under 1000 lines and with function blocks I've reused from my previous EAs, then I'll not bother commenting the source code.

However, I always write release notes for every major and minor version. I always maintain a spreadsheet of version change history. And I always write a data dictionary when I've a very stable codebase.

Geez Cloudbreaker,

You an I have almost same beginnings

Of course 25 years ago you kind of had to make your own commit tools.

I find that my code lives own through libraries and nothing hurts more than coming back to some obscur logic and trying to figure out what the heck I was trying to do.

I also like to write my code out in English when ever possible to reduce need for comments

#define TYPE1 1
#define TYPE2 2
#define PASS  1
#define FAIL  0

if (PASS) {
   code block
}

if ( ! FAIL ) {
   code block
}

switch (type) {
   case TYPE1: break;
   case TYPE2: break;
}

hitTarget      = NormalizeDouble(testPrice - targetPrice,Digits) >= 0;

switch (targetLevel) {
   case OA_TARGET_2:
      if (hitTarget) {
         _stoploss         = OrderArray[s][t][OA_OPEN_PRICE];
         _nextStoploss     = OrderArray[s][t][OA_TARGET_1];
         _nextTargetLevel  = OA_TARGET_3;
         _nextLimit        = OA_TARGET_4;
         _lots             = PercentLots (0.5);
         percentProfit     = 50;
         _targetDescr      = "OA_TARGET_2";
      } 
      break;
}

Not worrying about long variables allows for more readable code and less commenting.

I WILL SAY that i will always COMMIT my code.

I suggest you look into tortoise which works for both svn and cvs

I can not say how many times I am thankful for being able to remove changes or tag code revisions before i screw things up.

http://tortoisesvn.net/

http://tortoisecvs.org/

johnM, tell me please - in simple concepts, what is needed ..cvs and/or ...svn and maybe simple howTo's of implementation on single user winXP box.

I ask because cannot grasp the thrust of these sites. Of course I fully see purpose of source code control - especially within programmer teams.

Also, I feel the frustration of "damn, why the heck did I not make a new version BEFORE hacking it to death" with resultant nightmare that is almost impossible to regress back to original.

Assume all guilty of hacking perfectly ok code - only to end up with !ok code... and [of course] no backups etc.

Your indulgence much sought.

Best

Sorry been deep into coding, it is so frustrating to correct a bad trade only to have it eliminate good trades seems I have a net gain of 1.25 no matter what, well that is EA programming I suppose.

CVS and SVN are taste, I have always been a cvs user and since SVN was new I never made the change. Having retired from Cisco I installed Tortoise SVN.

The hardest concept perhaps is how to set up the repository. I am going to ASSume that you are not going to do branching and stuff and only want to protect against DAMN why the heck did I do that.

The help available with tortoise is very good to be able to do this.

Just install the tortoise SVN software

then open up and explore folder window and select the folder you wish to create the "Repository". This can be a common repository for all projects e.g.

C:\SVNRepository\trunk\project1

C:\SVNRepository\trunk\project2

or you can create a repository for each project e.g.

C:\SVNproject1\trunk

C:\SVNproject2\trunk

The repository is simply created by creating a new base folder SVNRepository or SVNproject

create the top directory

Right click and select TortoiseSVN then select Create Repository here

Now set up the repository

Right click the the repository directory and select TortoiseSVN:Repository Browser

Now add the folders trunk, branches and tags

It is unlikely that you will ever need branches unless you are doing commercial scripts.

Tags is great to use to mark a point in your development where you may want to return to continue development after you realize that you F'd it all up

Now to use the repository, explore the MT4 expert folder

right click the expert folder and copy it

now paste it into a temp folder

keep the directory structure, but delete all files you are not interested in all ex4 files, since these are built, all mq* files that you are not going to work on. i.e. you should be left with only mqh and mq4 experts, scripts, indicators and libraries that you will work with.

Having cleaned up your initial files

right click on the Temp/expert folder and select TortoiseSVN: Import ALWAYS ALWAYS ALWAYS enter a message so you can determine what you are committing to the repository. best to keep a log of what you have done and then enter this as the comment.

Once you import your initial files to the repository you ca get a working copy of them. go back to MT4 experts folder in explorer

right cliick select TortoiseSVN:Checkout

set url of your import file:///C:/SVNRepository/trunk/experts

set checkout directory C:\MT4TopDirectory\

NOTE:

DO NOT CHECKOUT to the experts directory or you will have an experts\experts directory structure.

This will now checkout the repository\experts files into the MT4 directory structure. You will see that these files are now "versioned" or merged

Now all you have to do is right click on the experts directory and select commit to see what files have changed and bulk commit them to the repository or single files one at a time.

CAVEAT

New files must be added first to the repository before they can be committed this is a two step process. Right click on the new file you which to commit. select TortoiseSVN: Add

give a reason like "initial add file"

OK

Now Right click file again now you have the option to Update or Commit the file to repository

Commit the file to the repository to get it checked in for the first time, don't forget to add a comment.

Now to get back to your previous version, either rename the file (I use an _ so I can still get at my changes) and then

right click the directory SVN Update, you can un select files you do not wish to update.

I hope this helps.

John

I don't comment my code much. Commenting code could be misleading as code changes fast but then you forget to changes comments.

I wish I commented on top of some various versions of the same indicator what was the difference from one version to the next.

Thank you vmuch John M. That was some post full of help - really appreciate and will take it on board.

Regards