Readability

From SpaceElevatorWiki.com
Revision as of 21:49, 10 July 2008 by Keithcu (talk | contribs)
Jump to navigationJump to search

I have been looking through the existing Delphi robot code.

After the mechanical port, we should do a bunch of renames and cleanup.

I don't know what this variable does: oPrivGearNb

I think its name should be obvious. I think the "o" is unnecessary, and I think the rest doesn't tell me what it is. If the Nb means number, that is also not really necessary. We don't have to make variable names long, just make the names as predictable and natural. If we decide to use an abbreviation, lets use that abbreviation everywhere. Maybe we should create a table of abbreviations.

Let's use the C# Boundary to make nice type and variable names..

I think we should not do this:

  property RaceTimeBeforeNext: Double
     read oRaceTimeBeforeNext;

That just wastes space and pollutes the namespace. Lets just expose things as a data member, we can make it a property one day without changing any the other code. It gets us nothing.

I think with an afternoon of search and replace across files we could make the Torcs robot easier for a random programmer on the street.

I presume the data for RaceTimeBeforeNext is needed, but it sure sounds like a weird information.

Just imagine if variables had totally random names. How much would that slow progress?

Another comment: Don't add comments that are obvious

  private Single TrackLength = 0.0f;      // Length of the Track

The comment there adds no value, and adds text. I go and read the comment, thinking it will help me understand the code, but it doesn't help and just wastes time!

Also, don't put comments on the end of a line:

  Single catchDist = Math.Min  // Calc distance to catch it
  (opp.CatchDist,              // Opponents catch distance
  C.CatchFactor                // Scaled distance 

when you do that, it makes it hard to change the code, because the comments are in the way.